hvdcache.h File Reference

eHVD cache for raster backends. More...

#include "std.h"
#include "rrevents.h"
#include "swmemapi.h"
#include "hvdlib.h"

Data Structures
struct	HVD_cache_params
	Parameters for the HVD cache instance. More...
struct	HVD_cache_fns
	HVD cache API functions. More...

Macros
#define	HVD_PURGE_NEXT(p_)   ((p_) << 4)
	Macro to construct libHVD cache purging policies. More...
#define	HVD_PURGE_DEFAULT
	Suggested default purging strategy. This will select from a subset of the cache, purging the least expected time, then the least expected area, then the least expected size, then the least hits, then the least area.
#define	HVD_CACHE_PARAMS_INIT
	Default initializer for HVD cache params.
#define	LIBHVD_BASE   "LIBHVD_BASE"
	Name of an implementation of a process-local memory eHVD cache suitable for use as a base class of a single RIP eHVD cache.
#define	LIBHVD_SHM_BASE   "LIBHVD_SHM_BASE"
	Name an implementation of a shared memory eHVD cache suitable for use as a base class of a Scalable RIP eHVD cache.

Typedefs
typedef int	HVD_cache_policy
	Type definition for the HVD cache purge policy.
typedef struct HVD_cache_params	HVD_cache_params
	Parameters for the HVD cache instance.
typedef void()	HVD_element_has_rasters_fn(void *data, HVD_result status, unsigned int nRasters, const int32 extent[4])
	Function type to notify caller of raster presence or absence in response to HVD_element_has_rasters(). This function is called either during processing of HVD_element_has_rasters(), or asynchronously to provide the results of the HVD_element_has_rasters() request. More...

Enumerations
enum	HVD_cache_policy_values {   HVD_PURGE_RANDOMLY = 1 , HVD_PURGE_LEAST_HITS , HVD_PURGE_LEAST_AREA , HVD_PURGE_SMALLEST ,   HVD_PURGE_LARGEST , HVD_PURGE_LEAST_AREA_EXPECTED , HVD_PURGE_SMALLEST_EXPECTED , HVD_PURGE_LEAST_TIME ,   HVD_PURGE_LEAST_TIME_EXPECTED }
	Possible values of the HVD element cache purging policy. More...

Functions
void	HVD_set_cache_limit (size_t limit)
	Set the total storage limit for all HVD caches. More...
size_t	HVD_cache_size (HVD_cache *cache, HVD_recovery_reason reason)
	Return the approximate amount of memory in use in all HVD caches. More...
void	HVD_cache_recover (HVD_cache *cache, HVD_recovery_reason reason, size_t *recover)
	Try to recover memory from all HVD caches, regardless of cache limit. More...
HVD_result	HVD_cache_create (const HVD_cache_params *params, HVD_cache **ppCache)
	Find or create an HVD element cache instance for a cache and setup ID. More...
void	HVD_cache_destroy (HVD_cache **ppCache, HVD_destroy_reason reason)
	Remove a reference to an HVD cache instance, possibly destroying the cache and all raster data stored. More...
void	HVD_cache_get_ids (const HVD_cache *cache, const uint8 **pCacheId, const uint8 **pSetupId)
	Get the cache and setup IDs from an HVD cache. More...
HVD_result	HVD_cache_element_add (HVD_cache *cache, const uint8 id[16], const int32 extent[4])
	Create (if necessary) and add an HVD element to an HVD cache instance. More...
HVD_result	HVD_element_lock (HVD_cache *cache, const uint8 id[16])
	Lock an HVD element. Locked elements cannot have their content removed. More...
HVD_result	HVD_element_unlock (HVD_cache *cache, const uint8 id[16])
	Unlock an HVD element that was previously locked. More...
HVD_result	HVD_element_hits (HVD_cache *cache, const uint8 id[16], int *hits)
	Update the number of hits on an HVD cache element. More...
HVD_result	HVD_element_pending (HVD_cache *cache, const uint8 id[16])
	Note that rasters for an HVD cache element have been requested. More...
HVD_result	HVD_element_add_raster (HVD_cache *cache, const uint8 elementId[16], unsigned int nExpected, void *hraster, const char *rasterId, size_t size)
	Inform the HVD cache that we are adding raster data for an HVD element. More...
void	HVD_element_has_rasters (HVD_cache *cache, const uint8 id[16], HVD_element_has_rasters_fn *notify, void *data)
	Submit a request to determine whether all of the rasters for an element been received. More...
void *	HVD_element_get_raster (HVD_cache *cache, const uint8 id[16], unsigned int index)
	Getter for HVD element raster information. More...
HqBool	HVD_cache_fns_valid (const HVD_cache_fns *cache_fns)
	Determine if an HVD cache implementation can be instantiated. More...

Detailed Description

eHVD cache for raster backends.

The element cache is responsible for managing eHVD elements: tracking creation, locking, unlocking, and hit counting on cached elements, purging unused elements to stay within specified storage limits, responding to cache size and purging requests, and responding to queries about elements present in the cache. The element cache may be specialised to use different storage methods for elements.

The Harlequin RIP SDK contains specialisations of eHVD element storage for local memory framebuffers (declared in hvdmemfb.h); shared memory framebuffers (declared in hvdshmfb.h); and compressible, purgeable raster stores (declared in hvdrstore.h).

The default HVD cache functions exported here are not fully thread safe:
they can cope with the cache purging and sizing functions
HVD_set_cache_limit(), HVD_cache_size(), and HVD_cache_recover() being
called asynchronously with respect to the rest of the API. However, they
expect the other functions to be called synchronously with respect to
each other. The primary use cases for the HVD cache interface has it
connected to a client that ensures non-concurrent access for these
functions. If used in a context that requires concurrent access, the cache
API can be proxied by a layer that uses mutexes around vulnerable calls.

Macro Definition Documentation

HVD_PURGE_NEXT

#define HVD_PURGE_NEXT

(

p_

)

((p_) << 4)

Macro to construct libHVD cache purging policies.

Cache policies can be combined by shifting and adding different policy strategies together. The test in the lowest bits will be performed first, then the test in the next lowest bits, and so on until the remaining bits are zero. This macro can be used to combine policies, for example:

policy = HVD_PURGE_LEAST_HITS + HVD_PURGE_NEXT(HVD_PURGE_SMALLEST + HVD_PURGE_NEXT(HVD_PURGE_LEAST_AREA))

Finally, if the cache policy is negative, the search to find purgeable elements will consider a small subset of the elements, ranking them in the order specified by the absolute value of the policy.

Typedef Documentation

HVD_element_has_rasters_fn

typedef void() HVD_element_has_rasters_fn(void *data, HVD_result status, unsigned int nRasters, const int32 extent[4])

Function type to notify caller of raster presence or absence in response to HVD_element_has_rasters(). This function is called either during processing of HVD_element_has_rasters(), or asynchronously to provide the results of the HVD_element_has_rasters() request.

Parameters

[in]	data	The opaque data pointer passed to HVD_element_has_rasters().
[in]	status	The status of the HVD_element_has_rasters() request. If this is HVD_SUCCESS, then all rasters for the element have been received. If this is HVD_SUCCESS_INCOMPLETE, then more rasters are expected for this element. Any other status is an error, and should be propagated to the waiter. The HVD cache always expects at least one raster per element, so if there have been no calls to HVD_element_add_raster() and no errors, status will be HVD_SUCCESS_INCOMPLETE.
[in]	nRasters	The number of rasters added to the element. If status is not HVD_SUCCESS or HVD_SUCCESS_INCOMPLETE, then this value may be invalid and should not be used.
[in]	extent	The extent of the element. If status is not HVD_SUCCESS or HVD_SUCCESS_INCOMPLETE, then this value be invalid or NULL and should not be used.

Enumeration Type Documentation

HVD_cache_policy_values

enum HVD_cache_policy_values

Possible values of the HVD element cache purging policy.

Enumerator
HVD_PURGE_RANDOMLY	Purge elements randomly. This will result in the smallest time purging elements from the cache, possibly at the expense of more regeneration time.
HVD_PURGE_LEAST_HITS	Purge elements with fewest hits. Hits are added when an element is used in a page definition, and removed as pages are purged. If shared across multiple RIPs, this should be a good proxy for retaining pages that are most likely to be used again.
HVD_PURGE_LEAST_AREA	Purge elements with the smallest area preferentially. This should reduce regeneration time for cache misses if the larger elements used can all be retained.
HVD_PURGE_SMALLEST	Purge elements with the smallest raster storage size preferentially. This should reduce regeneration time for cache misses if the larger elements used can all be retained.
HVD_PURGE_LARGEST	Purge elements with the largest raster storage size preferentially. This should retain more small elements in the cache, resulting in higher hit rates, but increasing regeneration time for cache misses.
HVD_PURGE_LEAST_AREA_EXPECTED	Purge elements with the least expected area preferentially. This is the area of the element multiplied by the number of hits. This should retain elements that have the highest cost to regenerate, assuming the area of the element correlates with its complexity.
HVD_PURGE_SMALLEST_EXPECTED	Purge elements with the least expected raster storage size. This is the raster size of the element multiplied by the number of hits. This should retain elements that have the highest cost to regenerate, assuming the raster size of the element correlates with its complexity.
HVD_PURGE_LEAST_TIME	Purge elements that took the least time to generate preferentially. This should retain elements that take more time to regenerate.
HVD_PURGE_LEAST_TIME_EXPECTED	Purge elements that took the least time to generate, adjusted for the element hits. This is the time the element rasters took to generate multiplied by the number of hits. This should retain elements that have the highest cost in time to regenerate.

Function Documentation

HVD_cache_create()

HVD_result HVD_cache_create	(	const HVD_cache_params *	params,
		HVD_cache **	ppCache
	)

Find or create an HVD element cache instance for a cache and setup ID.

Parameters

[in]	params	The parameters for this HVD cache instance.
[out]	ppCache	A location to store the HVD cache created.

Return values

HVD_SUCCESS	The HVD cache instance was found or created successfully, and a handle was stored in ppCache. If this function succeeds, HVD_cache_destroy() must be called to destroy it when the connection is disconnected.
HVD_ERROR_INVALID_PARAMS	The HVD cache instance could not be created because the parameters were invalid.
HVD_ERROR_NO_MEMORY	The HVD cache instance could not be created because of memory exhaustion.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

All of the params fields must match in order to return an existing cache instance. If the setup_id is empty, then existing cache instances will never be returned.

HVD_cache_destroy()

void HVD_cache_destroy	(	HVD_cache **	ppCache,
		HVD_destroy_reason	reason
	)

Remove a reference to an HVD cache instance, possibly destroying the cache and all raster data stored.

Parameters

[in,out]	ppCache	The location to find the cache instance. This will be reset to NULL on exit.
[in]	reason	The reason that this cache instance is being destroyed. This option is intended for use in error conditions or at shutdown, to ensure shared resources are recovered.

HVD_cache_element_add()

HVD_result HVD_cache_element_add	(	HVD_cache *	cache,
		const uint8	id[16],
		const int32	extent[4]
	)

Create (if necessary) and add an HVD element to an HVD cache instance.

Parameters

[in]	cache	The cache instance to add the element to
[in]	id	The ID of the element to add.
[in]	extent	The extent of HVD element to add. The extent is a half-open range, with pixels at x1 and y1 included, but those at x2 or y2 excluded.

Return values

HVD_SUCCESS	The element was added to the cache successfully.
HVD_ERROR_NO_MEMORY	The element could not be added to the cache, because the cache could not allocate memory.
HVD_ERROR_ELEMENT_MISMATCH	The element was already found in the cache, but had a different extent.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

HVD_cache_fns_valid()

HqBool HVD_cache_fns_valid

(

const HVD_cache_fns *

cache_fns

)

Determine if an HVD cache implementation can be instantiated.

Parameters

[in]

cache_fns

The cache functions to check.

Return values

TRUE	All of the required fields in cache_fns have values.
FALSE	Some of the required fields in cache_fns have invalid values.

This function is used to prevent instantiation of incomplete HVD cache implementations. This may happen if an HVD base class is used instead of a derived implementation.

HVD_cache_get_ids()

void HVD_cache_get_ids	(	const HVD_cache *	cache,
		const uint8 **	pCacheId,
		const uint8 **	pSetupId
	)

Get the cache and setup IDs from an HVD cache.

Parameters

[in]	cache	The cache instance to get the IDs for.
[out]	pCacheId	A location to store the cache ID, or NULL if it should not be returned.
[out]	pSetupId	A location to store the setup ID, or NULL if it should not be returned.

This may be used for debug output, or to construct file or object names unique to the cache or its elements.

HVD_cache_recover()

void HVD_cache_recover	(	HVD_cache *	cache,
		HVD_recovery_reason	reason,
		size_t *	recover
	)

Try to recover memory from all HVD caches, regardless of cache limit.

This function may be used to recover memory or storage from HVD caches, even if the total memory in use is lower than the pre-set cache limit.

Parameters

[in]	cache	The cache instance to recover memory or storage from. If this is NULL, memory will be recovered from all HVD caches if possible.
[in]	reason	The reason for this recovery operation. This parameter may be used to exclude elements or rasters from low-memory recovery, if they do not contribute to the type of memory requested. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover().
[in,out]	recover	A location where the amount of data to recover is stored. On exit, this will be updated to the amount remaining to recover.

HVD_cache_size()

size_t HVD_cache_size	(	HVD_cache *	cache,
		HVD_recovery_reason	reason
	)

Return the approximate amount of memory in use in all HVD caches.

Parameters

[in]	cache	The cache instance to get the size of. If this is NULL, the size returned will be the approximate amount from all HVD caches, filtered by the HVD_cache_fns::recovery_filter using reason.
[in]	reason	The reason for this recovery operation. This parameter may be used to exclude elements or rasters from low-memory recovery, if they do not contribute to the type of memory requested. The core RIP will only use non-negative values for calls to HVD_cache_size() and HVD_cache_recover().

Returns

An approximate number of bytes in all HVD caches, filtered by the HVD_cache_fns::recovery_filter using reason.

HVD_element_add_raster()

HVD_result HVD_element_add_raster	(	HVD_cache *	cache,
		const uint8	elementId[16],
		unsigned int	nExpected,
		void *	hraster,
		const char *	rasterId,
		size_t	size
	)

Inform the HVD cache that we are adding raster data for an HVD element.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	elementId	The ID of the element to add a raster for. This function does not change the reference count for the element.
[in]	nExpected	The total number of rasters that we expect to add for this element. In general, this number should be set on the first call of this function for an element, and the same value should be used for all calls on the same element thereafter. It is possible to revise the expected number downwards if some rasters are omitted, or upwards if more rasters are added, but it should never be less than the number of rasters added (including this one), and it should never be increased after all of the expected rasters have been received. When all of the rasters that are expected have been received, the element is marked as ready for use, and pages using this element may be output immediately.
[in]	hraster	A raster handle. This is used to identify the raster data when the page is output, or the element is destroyed.
[in]	rasterId	A raster handle identifier. This is a zero-terminated string used when the HVD cache is hosted in a different Scalable RIP HVD process. The raster handle identifier is passed to the process hosting the HVD cache, to allow it to identify and retain the raster, and may be passed to other processes to allow them to identify and access the raster data for output. For local HVD cache implementations, this may be NULL.
[in]	size	The size of the raster data stored. This is counted against the cache limit.

Return values

HVD_SUCCESS	The raster handle was added to the element successfully. This was the final raster expected.
HVD_SUCCESS_INCOMPLETE	The raster handle was added to the element successfully. This was not the final raster expected.
HVD_ERROR_INVALID_PARAMS	There was no cache or no element to add the raster to.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.
HVD_ERROR_EXCESS_RASTERS	The number of rasters is more than the number expected, including the raster currently being added.
HVD_ERROR_NO_MEMORY	The raster handle could not be added to the element, because the cache could not allocate memory.

Returns

Any other return value greater than MON_CLASS_ERROR is an error UID. The subclass, PS error type, and UID for the error can be deconstructed using the macros in monevent.h.

All elements expect to have at least one raster, and will not be marked as complete until nExpected rasters have been delivered.

If the return value is HVD_SUCCESS or HVD_SUCCESS_INCOMPLETE, the raster handle has been retained by the HVD element, and must remain valid until the HVD cache calls the raster release callback function with the handle. Raster release calls will happen during the HVD disconnect call if rendering is aborted, or when the element is purged from the cache.

For any other return value, the caller should dispose of the raster data.

Raster handles will be provided to the output function callback, so the client can identify all of the rasters for each element output.

HVD_element_get_raster()

void* HVD_element_get_raster	(	HVD_cache *	cache,
		const uint8	id[16],
		unsigned int	index
	)

Getter for HVD element raster information.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to get raster information for. This function does not change the reference count for the element.
[in]	index	An index into the rasters in the element. This must be less than the nRasters output value of HVD_element_has_rasters().

Returns

The raster handle for raster index.

HVD_element_has_rasters()

void HVD_element_has_rasters	(	HVD_cache *	cache,
		const uint8	id[16],
		HVD_element_has_rasters_fn *	notify,
		void *	data
	)

Submit a request to determine whether all of the rasters for an element been received.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to test. This function does not change the reference count for the element.
[in]	notify	A callback function through which the raster status information will be delivered. The cache implementation may deliver raster status information through this function asynchronously, or may call this function immediately. The notify callback function will always be called, even if there is an error in setting up the raster notification request.
[in]	data	An opaque data pointer passed to the notify function.

All errors are reported through the notify() callback function. Errors in creating the request will result in an immediate call to notify(), possibly using a NULL extent.

Note

The HVD cache client must not destroy the cache while there are any notifications pending.

HVD_element_hits()

HVD_result HVD_element_hits	(	HVD_cache *	cache,
		const uint8	id[16],
		int *	hits
	)

Update the number of hits on an HVD cache element.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to change the hit count on. This function does not change the reference count for the element.
[in,out]	hits	The location of the hit count. On entry, this is the change in the number of hits requested. On exit, this is updated to be the current hit count of the element.

Return values

HVD_SUCCESS	The hit count of the element was updated as requested, and the new hit count is valid.
HVD_ERROR_INVALID_PARAMS	There was no cache, or no element, or nowhere to find the hit count.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.
HVD_ERROR_UNDERFLOW_HITS	The requested change in hits would underflow the element's hit count.

HVD_element_lock()

HVD_result HVD_element_lock	(	HVD_cache *	cache,
		const uint8	id[16]
	)

Lock an HVD element. Locked elements cannot have their content removed.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to lock. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was locked successfully.
HVD_ERROR_INVALID_PARAMS	There was no cache, or no element to lock.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.
HVD_ERROR_NOT_PENDING	The element was not pending; no rasters have been requested for it. The element was not locked.

HVD_element_pending()

HVD_result HVD_element_pending	(	HVD_cache *	cache,
		const uint8	id[16]
	)

Note that rasters for an HVD cache element have been requested.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to mark pending. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was marked pending.
HVD_ERROR_INVALID_PARAMS	There was no cache, or no element to mark.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.
HVD_ERROR_ALREADY_PENDING	The element was already pending.

HVD_element_unlock()

HVD_result HVD_element_unlock	(	HVD_cache *	cache,
		const uint8	id[16]
	)

Unlock an HVD element that was previously locked.

Parameters

[in]	cache	The cache instance the element is stored in.
[in]	id	The ID of the element to unlock. This function does not change the reference count for the element.

Return values

HVD_SUCCESS	The element was unlocked.
HVD_ERROR_INVALID_PARAMS	There was no cache, or no element to unlock.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.
HVD_ERROR_NOT_LOCKED	The element was not previously locked.

HVD_set_cache_limit()

void HVD_set_cache_limit

(

size_t

limit

)

Set the total storage limit for all HVD caches.

The cache limit is used as the trigger to purge HVD element rasters from the cache. HVD element rasters are only purged if they are not locked and they have raster data. The sizes declared when rasters were added to the cache are used to determine how much space an element takes.

Individual HVD caches may have different cache purging policies.

Parameters

[in]

limit

The storage limit, expressed in bytes, that the HVD element cache will try to stay within. If this is zero, the cache can consume unlimited storage.