==========================================
kissdx picture pre-loading – Specification
==========================================


BACKGROUND

The loading of a picture to a KiSS player can take a long time from the user
asks for the picture till it's displayed on screen.  The objective of picture
pre-loading is to reduce the time period that the user has to wait.


POSSIBLE SOLUTIONS

1. Actual pre-loading into memory on the server

This could be done, but would require a common memory block and
process-to-process communications to manage this common memory block.

2. Pre-caching

Instead of actual pre-loading into memory, pre-caching the picture in kissdx's
scaled picture cache would go a long way towards reducing wait time because
 -	The scaling is already done when the picture is requested
 -	The scaled picture is small and requires little network traffic

Pre-caching is the selected solution.


DEFINITIONS

The CURRENT PICTURE is defined as the picture that the user is currently
viewing on the player.

The NEXT PICTURE is defined as the picture that will be requested if the user
presses the Next button on the player's remote.
If the current picture is the last picture in the user's folder listing then
the next picture is defined to be the first picture in the same list.
If there is only one picture in the user's list then there is no next picture.
If there is no current picture then there is no next picture.


REQUIREMENTS

The feature should be enabled automatically if scaled picture caching is enabled.

If the cache size limit is < 2, the feature should effectively be disabled.

Pre-caching of the next picture should be started immediately after serving the
current picture to the player.

If the picture is already in the cache, nothing should be done.

The pre-caching operation should be performed "in the background", not disturbing
the further operation of kissdx.

The pre-caching operation should be stoppable with a signal.  This may not be
feasible to implement without changing libjpeg, so it is not a must.

If the pre-caching operation is not stoppable, it must be possible for other
processes to wait for it to complete in a resource-friendly manner.


IMPLEMENTATION

A dedicated status file will be used to hold the state of the current pre-caching
operation.  We use a regular disk file and we create it in the picture cache root
directory:
<picture-folder>/.piccache/.pre-caching-status

The information structure that we write to / read from the status file has the
following data:
	1.	The version number of the caching code that populated this structure
	2.	The size in bytes of this structure
	3.	The GMT time when this structure was written to the status file.
		We may need this to detect that a pre-caching process has crashed and
		left this structure behind.
	4.	The PID (process id) of the process that populated this structure.
	5.	The original full filename of the picture file that is being re-cached

The structure above has no flag telling whether a pre-caching operation is in
progress:  When no pre-caching operation is in progress, the status file should
be non-existent.

Pre-caching of the next picture will be done by the same process that has just
sent the current picture, immediately after the current picture has been sent.
It should be safe to assume that this condition is met when there are no more
GET commands coming in from the player for an ACTION command.

When a process has served a picture and wants to pre-cache the next one, it
must read the status file and see if a pre-caching operation is already underway.
If pre-caching is already in operation, we will just exit normally without
pre-caching;  we want only one pre-caching operation to be active at any time.

Immediately before starting the pre-caching operation, we must write to the
status file the current pre-caching status so other processes can see what we
are doing.

Immediately after the pre-caching operation finishes, we must write to the
status file to clear out the pre-caching status so other processes can see
that we are done.
We must do this whether the actual pre-caching was successful or not.

When receiving a request for a picture, we must check whether that picture
is currently being pre-cached.
If it is, we must wait for the pre-caching operation to finish.
If it is not, we can proceed normally

NOTES FOR DEVELOPMENT

1.	Create a function that finds the next picture: get_next_picture().
	Create this in connection.c, using scandir with the same sort function as
	directory lists, and an internal selector function that returns true only
	for the next picture.

2.	Call get_next_picture() from connection.c, when finished sending current
	picture.  If next picture was found, call piccache_get_entry_filename()
	to check whether it's in the cache already.
	If it's NOT in the cache alredy:
	a)	Write new status to status file.
	b)	Call CachedSizeResizedJPEG() to add it to cache.
	c)	Clear status from status file.

3.	Before sending a picture, wait for pre-caching to complete if the 
	requested picture is currently being pre-cached.


STATUS

Implemented in kissdx 0.13-7.