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_) << 3)
	Macro to construct libHVD cache purging policies. More...

#define	HVD_CACHE_PARAMS_INIT
	Default initialiser for HVD cache params.

Typedefs
typedef void()	HVD_element_release_fn(HVD_element pElement, void helement)
	Function type to dispose of element handles. This is called for each element when it is removed from the HVD cache and the element handle is non-NULL. More...

typedef void()	HVD_raster_release_fn(HVD_element pElement, void hraster)
	Function type to dispose of raster handles. This is called for each non-NULL raster previously added to an element. More...

typedef HqBool()	HVD_recovery_filter_fn(HVD_element *pElement, HVD_recovery_reason_t reason)
	Function type to filter HVD elements for recovery when called from a low-memory handler. More...

typedef size_t()	HVD_raster_purge_fn(HVD_element pElement, void hraster, size_t *recover)
	Function type to purge memory for raster handles. This is called for each non-NULL raster previously added to an element when running low on memory in the cache. More...

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.

Enumerations
enum	{ HVD_PURGE_RANDOMLY = 1 , HVD_PURGE_LEAST_HITS , HVD_PURGE_LEAST_USED , HVD_PURGE_SMALLEST , HVD_PURGE_LARGEST }
	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_t reason)
	Return the approximate amount of memory in use in all HVD caches. More...

void	HVD_cache_recover (HVD_cache cache, size_t recover, HVD_recovery_reason_t reason)
	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 element cache instance for a cache and setup ID. More...

void	HVD_cache_destroy (HVD_cache **ppCache, HqBool force)
	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 SWMSG_RR_ELEMENT_DEFINE elementdef, HVD_element **ppElement)
	Create (if necessary) and add an HVD element to an HVD cache instance. More...

HVD_element *	HVD_cache_element_lookup (HVD_cache *cache, const uint8 id[16])
	Look up an HVD element in the cache. More...

HVD_result	HVD_element_lock (HVD_element *pElement)
	Lock an HVD element. Locked elements cannot have their content removed. More...

HVD_result	HVD_element_unlock (HVD_element *pElement)
	Unlock an HVD element that was previously locked. More...

int	HVD_element_hits (HVD_element *pElement, int delta)
	Update the number of hits on an HVD cache element. More...

HVD_result	HVD_element_pending (HVD_element *pElement)
	Note that rasters for an HVD cache element have been requested. More...

void	HVD_element_release (HVD_element **ppElement)
	Release a reference to an HVD cache element. More...

void	HVD_element_set_data (HVD_element pElement, void data)
	Setter for HVD element data. More...

void *	HVD_element_get_data (const HVD_element *pElement)
	Getter for HVD element data. More...

HVD_result	HVD_element_add_raster (HVD_element pElement, unsigned int nExpected, void hraster, size_t size)
	Inform the HVD cache that we are adding raster data for an HVD element. More...

HVD_result	HVD_element_has_rasters (const HVD_element element, unsigned int nRasters, unsigned int *nRastersExpected)
	Have all of the rasters for an element been received? More...

void *	HVD_element_get_raster (const HVD_element *pElement, unsigned int index)
	Getter for HVD element raster information. More...

void	HVD_element_get_extent (const HVD_element *pElement, int32 extent[4])
	Getter for HVD element extent information. More...

const uint8 *	HVD_element_get_ids (const HVD_element element, const uint8 pCacheId, const uint8 *pSetupId)
	Get the cache, setup, and element IDs from an HVD element. 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_) << 3)

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_USED))

HVD_PURGE_NEXT

#define HVD_PURGE_NEXT(p_)

Macro to construct libHVD cache purging policies.

Definition: hvdcache.h:161

HVD_PURGE_LEAST_USED

@ HVD_PURGE_LEAST_USED

Definition: hvdcache.h:134

HVD_PURGE_LEAST_HITS

@ HVD_PURGE_LEAST_HITS

Definition: hvdcache.h:128

HVD_PURGE_SMALLEST

@ HVD_PURGE_SMALLEST

Definition: hvdcache.h:138

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_release_fn

typedef void() HVD_element_release_fn(HVD_element *pElement, void *helement)

Function type to dispose of element handles. This is called for each element when it is removed from the HVD cache and the element handle is non-NULL.

Parameters

[in]	pElement	The element which the element handle was attached to.
[in]	helement	Data attached to the element using HVD_element_set_data().

◆ HVD_raster_purge_fn

typedef size_t() HVD_raster_purge_fn(HVD_element *pElement, void *hraster, size_t *recover)

Function type to purge memory for raster handles. This is called for each non-NULL raster previously added to an element when running low on memory in the cache.

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().
[in,out]	recover	A location where the amount of memory the purge operation still needs to recover is stored. On exit, the raster purge function should update this to the amount that is still needed after compressing, purging to storage, or otherwise reducing memory consumption. The reduction in memory may exceed the amount needed, in which case the raster purge function should set *recover to zero on exit.

Returns: The new size of the raster data after compressing, purging to storage, or otherwise reducing memory consumption.

The purge function, if present, may be called while an element is locked. It must not discard raster data, but may make it slower to access.

◆ HVD_raster_release_fn

typedef void() HVD_raster_release_fn(HVD_element *pElement, void *hraster)

Function type to dispose of raster handles. This is called for each non-NULL raster previously added to an element.

Parameters

[in]	pElement	The element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().

◆ HVD_recovery_filter_fn

typedef HqBool() HVD_recovery_filter_fn(HVD_element *pElement, HVD_recovery_reason_t reason)

Function type to filter HVD elements for recovery when called from a low-memory handler.

Parameters

[in]	pElement	The element that might be removed from the cache.
[in]	reason	The reason supplied to the call to HVD_cache_size() or HVD_cache_recover(). 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.

Return values

TRUE	The HVD raster is eligible for purging or removal.
FALSE	The HVD raster is not eligible for purging or removal.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

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_USED	Purge elements with the fewest references in the current page define. This allows elements that will not be used again in the current job to be purged first. Note that the Scalable RIP may keep job contexts open for multiple page ranges, this may purge elements that are globally significant, but are complete within the current page range.
HVD_PURGE_SMALLEST	Purge the smallest elements preferentially. This should reduce regeneration time for cache misses if the larger elements used can all be retained.
HVD_PURGE_LARGEST	Purge the largest elements preferentially. This should retain more small elements in the cache, resulting in higher hit rates, but increasing regeneration time for cache misses.

Function Documentation

◆ HVD_cache_create()

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

Find or create an 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,
		HqBool	force
	)

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]	force	Force destruction of the cache content and structures. 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 SWMSG_RR_ELEMENT_DEFINE *	elementdef,
		HVD_element **	ppElement
	)

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]	elementdef	The definition of the HVD element to add. If the extent of this element is (0,0,0,0), then the element ID is known, but the extent is not yet known. A further call to update the element will be expected in future.
[out]	ppElement	A location to store a reference to the element. This may be NULL, in which case no reference is stored. If non-NULL and the function is successful, then any existing element reference at this location is released, and the element reference stored must be released when the caller has done with it. If non-NULL and this function is not successful, no change is made to any existing element reference at this location.

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_element_lookup()

HVD_element* HVD_cache_element_lookup	(	HVD_cache *	cache,
		const uint8	id[16]
	)

Look up an HVD element in the cache.

Parameters

[in]	cache	The cache containing element id.
[in]	id	The ID of the element to lookup.

Returns: A pointer to the element, or NULL if the element was not discovered. If the element is discovered, a reference to it is acquired. This reference must be released by passing the element to a function that releases the reference.

◆ 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,
		size_t *	recover,
		HVD_recovery_reason_t	reason
	)

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

This function may be used to recover memory 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 from. If this is NULL, memory will be recovered from all HVD caches if possible.
[in,out]	recover	A location where the amount of memory to recover is stored. On exit, this will be updated to the amount remaining to recover.
[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: The actual number of bytes recovered.

◆ HVD_cache_size()

size_t HVD_cache_size	(	HVD_cache *	cache,
		HVD_recovery_reason_t	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_params::recovery_filter_fn 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_params::recovery_filter_fn using reason.

◆ HVD_element_add_raster()

HVD_result HVD_element_add_raster	(	HVD_element *	pElement,
		unsigned int	nExpected,
		void *	hraster,
		size_t	size
	)

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

Parameters

[in]	pElement	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]	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_NO_ELEMENT	There was no element to add the raster to.
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_data()

void* HVD_element_get_data ( const HVD_element * pElement )

Getter for HVD element data.

Parameters

[in] pElement The element to get element information for. This function does not change the reference count for the element.

Returns: The data attached to the element by the HVD_element_set_data() function.

◆ HVD_element_get_extent()

void HVD_element_get_extent	(	const HVD_element *	pElement,
		int32	extent[4]
	)

Getter for HVD element extent information.

Parameters

[in]	pElement	The element to get raster information for. This function does not change the reference count for the element.
[out]	extent	An array updated with the device space extent of the element.

◆ HVD_element_get_ids()

const uint8* HVD_element_get_ids	(	const HVD_element *	element,
		const uint8 **	pCacheId,
		const uint8 **	pSetupId
	)

Get the cache, setup, and element IDs from an HVD element.

Parameters

[in]	element	The element to get ids information for. This function does not change the reference count for the element.
[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.

Returns: The element ID. Returning this is a convenience so that this function may be used in-line in debug or logging messages when the cache id and setup ids are not needed.

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

◆ HVD_element_get_raster()

void* HVD_element_get_raster	(	const HVD_element *	pElement,
		unsigned int	index
	)

Getter for HVD element raster information.

Parameters

[in]	pElement	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()

HVD_result HVD_element_has_rasters	(	const HVD_element *	element,
		unsigned int *	nRasters,
		unsigned int *	nRastersExpected
	)

Have all of the rasters for an element been received?

Parameters

[in]	element	The element to test. This function does not change the reference count for the element.
[out]	nRasters	If non-NULL, a location to store the number of rasters currently ready. This is updated even if not all of the rasters have been received.
[out]	nRastersExpected	If non-NULL, a location to store the number of rasters currently expected. This is updated even if not all of the rasters have been received.

Return values

HVD_SUCCESS	All of the rasters for the element have been received.
HVD_SUCCESS_INCOMPLETE	More rasters are expected for this element.
HVD_ERROR_NO_ELEMENT	There was no element to check for rasters.
HVD_ERROR_*	There was an error with element or raster creation, this element will never have all of its rasters present.

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.

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, this function will return HVD_SUCCESS_INCOMPLETE.

◆ HVD_element_hits()

int HVD_element_hits	(	HVD_element *	pElement,
		int	delta
	)

Update the number of hits on an HVD cache element.

Parameters

[in]	pElement	The element to change the hit count on. This function does not change the reference count for the element.
[in]	delta	The change in the number of hits

Returns: The current hit count of the element, or a negative number for an error (MININT for no element, otherwise underflow; the caller probably doesn't care which, either indicates a programming error).

◆ HVD_element_lock()

HVD_result HVD_element_lock ( HVD_element * pElement )

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

Parameters

[in] pElement 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_NO_ELEMENT	There was no element to lock.
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_element * pElement )

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

Parameters

[in] pElement 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_NO_ELEMENT	There was no element to mark.
HVD_ERROR_ALREADY_PENDING	The element was already pending.

◆ HVD_element_release()

void HVD_element_release ( HVD_element ** ppElement )

Release a reference to an HVD cache element.

Parameters

[in,out] ppElement The reference to the element to release. This function is safe to call if *ppElement is NULL.

◆ HVD_element_set_data()

void HVD_element_set_data	(	HVD_element *	pElement,
		void *	data
	)

Setter for HVD element data.

Parameters

[in]	pElement	The element to set element information for. This function does not change the reference count for the element.
[in]	data	The data to set in the element

◆ HVD_element_unlock()

HVD_result HVD_element_unlock ( HVD_element * pElement )

Unlock an HVD element that was previously locked.

Parameters

[in] pElement 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_NO_ELEMENT	There was no element to unlock
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.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ HVD_PURGE_NEXT

Typedef Documentation

◆ HVD_element_release_fn

◆ HVD_raster_purge_fn

◆ HVD_raster_release_fn

◆ HVD_recovery_filter_fn

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ HVD_cache_create()

◆ HVD_cache_destroy()

◆ HVD_cache_element_add()

◆ HVD_cache_element_lookup()

◆ HVD_cache_get_ids()

◆ HVD_cache_recover()

◆ HVD_cache_size()

◆ HVD_element_add_raster()

◆ HVD_element_get_data()

◆ HVD_element_get_extent()

◆ HVD_element_get_ids()

◆ HVD_element_get_raster()

◆ HVD_element_has_rasters()

◆ HVD_element_hits()

◆ HVD_element_lock()

◆ HVD_element_pending()

◆ HVD_element_release()

◆ HVD_element_set_data()

◆ HVD_element_unlock()

◆ HVD_set_cache_limit()