HVD cache API functions. More...

#include "hvdcache.h"

Data Fields
size_t	size
	The size of this structure.

HVD_result(*	store_create )(const HVD_cache_params params, HVD_cache cache, void **ppStore)
	Create an element store for a new HVD element cache. More...

void(*	store_destroy )(HVD_cache cache, void *ppStore, HqBool reusable, HVD_destroy_reason reason)
	Destroy an HVD element store, after the last local reference to an HVD cache instance is released. More...

HqBool(*	store_size )(HVD_cache cache, void store, HVD_recovery_reason reason, size_t *total)
	Add the amount of recoverable memory in an element store to a total size. More...

HqBool(*	store_purge )(HVD_cache cache, void store, HVD_recovery_reason reason, size_t *recover, HVD_cache_policy cache_policy)
	Recover an amount of memory from an element store. More...

HVD_result(*	element_add )(HVD_cache cache, void store, const uint8 id[16], const int32 extent[4])
	Define an element, adding it to the element store if necessary. More...

HVD_result(*	element_query_lock )(HVD_cache cache, void store, const uint8 id[16])
	Function to lock an HVD element. Locked elements cannot have their content removed. More...

HVD_result(*	element_unlock )(HVD_cache cache, void store, const uint8 id[16])
	Function to unlock an HVD element that was previously locked. More...

HVD_result(*	element_hits )(HVD_cache cache, void store, const uint8 id[16], int *hits)
	Function to update the number of hits on an HVD cache element. More...

HVD_result(*	element_pending )(HVD_cache cache, void store, const uint8 id[16])
	Function to note that rasters for an HVD cache element have been requested. More...

HVD_result(*	element_add_raster )(HVD_cache cache, void store, const uint8 elementId[16], unsigned int nExpected, void hraster, const char rasterId, size_t size)
	Function to inform the HVD cache that we are adding raster data for an HVD element. More...

void(*	element_has_rasters )(HVD_cache cache, void store, const uint8 id[16], HVD_element_has_rasters_fn notify, void data)
	Function to determine if all of the rasters for an element been received. More...

void(*	raster_release )(HVD_cache cache, void store, const uint8 id[16], void *hraster)
	A function to call when an element with attached rasters is destroyed. This is called for each non-`NULL` raster attached to the element. More...

HVD_result(*	raster_find )(HVD_cache cache, void store, const uint8 elementId[16], unsigned int index, const char rasterId, void *pRaster)
	A function to call if the cache needs to find raster handles created by another Farm RIP in a Scalable RIP configuration. More...

size_t(*	raster_purge )(HVD_cache cache, void store, const uint8 id[16], void hraster, HVD_recovery_reason reason, size_t recover)
	A function to compress or purge data from rasters when running low on cache memory. This is called for each raster attached to an element. If not enough memory can be recovered by purging the top candidate elements, they will be released. More...

HqBool(*	recovery_filter )(HVD_cache cache, void store, const uint8 id[16], HVD_recovery_reason reason)
	A function to filter rasters to those suitable for compression or eviction when running low on memory. If this parameter is `NULL`, then all elements and rasters will be considered eligible for all low memory calls. More...

Detailed Description

HVD cache API functions.

These functions are used to interface the HVD event monitor and tracker to the HVD cache implementation. In the RIP, HVD cache implementations are registered in RDR as named RDRs of class RDR_NAMES_LIBHVD_CACHE_API, and the name used to register the cache implementation is passed to the event monitor to find and construct the cache instance. The API pointer and function pointers must remain valid for the lifetime of the event monitor.

Field Documentation

◆ element_add

HVD_result(* HVD_cache_fns::element_add) (HVD_cache *cache, void *store, const uint8 id[16], const int32 extent[4])

Define an element, adding it to the element store if necessary.

This method may be called more than once with the same element.

Parameters

[in]	cache	The HVD cache instance to add an element to.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to define.
[in]	extent	The extent of the element to define.

Return values

HVD_SUCCESS	The element was defined successfully, stored in ppElement if required, and a reference taken on the element if ppElement is non-`NULL`.
HVD_ERROR_INVALID_PARAMS	The cache or id parameters were invalid.
HVD_ERROR_MUTEX_FAILED	A mutual exclusion lock failed.
HVD_ERROR_ELEMENT_MISMATCH	An element with the same ID, but incompatible extent or state was already in the element store.
HVD_ERROR_NO_MEMORY	The cache implementation ran out of 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.

This method will only be called from the interpreter thread. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_add_raster

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

Function to inform the HVD cache that we are adding raster data for an HVD element.

Parameters

[in]	cache	The HVD cache instance containing element elementId.
[in]	store	The HVD element store implementation for cache.
[in]	elementId	The ID of the element to add a raster to.
[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.

This method may be called from arbitrary threads. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_has_rasters

void(* HVD_cache_fns::element_has_rasters) (HVD_cache *cache, void *store, const uint8 id[16], HVD_element_has_rasters_fn *notify, void *data)

Function to determine if all of the rasters for an element been received.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to test.
[in]	notify	A callback function through which the raster status information will be delivered. The element_has_rasters method 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.

This method may be called from arbitrary threads. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_hits

HVD_result(* HVD_cache_fns::element_hits) (HVD_cache *cache, void *store, const uint8 id[16], int *hits)

Function to update the number of hits on an HVD cache element.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to change the hit count on.
[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.

This method may be called from arbitrary threads. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_pending

HVD_result(* HVD_cache_fns::element_pending) (HVD_cache *cache, void *store, const uint8 id[16])

Function to note that rasters for an HVD cache element have been requested.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to mark pending.

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.

This method will only be called from the interpreter thread. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_query_lock

HVD_result(* HVD_cache_fns::element_query_lock) (HVD_cache *cache, void *store, const uint8 id[16])

Function to lock an HVD element. Locked elements cannot have their content removed.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to lock.

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.

This method will only be called from the interpreter thread. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ element_unlock

HVD_result(* HVD_cache_fns::element_unlock) (HVD_cache *cache, void *store, const uint8 id[16])

Function to unlock an HVD element that was previously locked.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element to unlock.

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.

This method may be called from arbitrary threads. It is the implementation's responsibility to ensure mutual exclusion between methods.

◆ raster_find

HVD_result(* HVD_cache_fns::raster_find) (HVD_cache *cache, void *store, const uint8 elementId[16], unsigned int index, const char *rasterId, void **pRaster)

A function to call if the cache needs to find raster handles created by another Farm RIP in a Scalable RIP configuration.

This method is optional, it is only used for cache implementations that need to find rasters produced by another process.

Parameters

[in]	cache	The HVD cache instance containing element elementId.
[in]	store	The HVD element store implementation for cache.
[in]	elementId	The ID of the element which the raster handle was attached to.
[in]	index	The raster index to find.
[in]	rasterId	The raster ID of this raster. This may be `NULL` if the raster backend did not supply a raster ID with the raster handle, or if the raster store did not pass on the raster ID.
[out]	pRaster	A location to store the raster handle found. This raster handle will be cached until the element is purged from the cache. When the element is purged from the cache, the raster handle will be released by calling the HVD_cache_fns::raster_release method supplied by the cache implementation.

Return values

HVD_SUCCESS	The raster handle was found and stored in *pRaster.
HVD_ERROR_NO_ELEMENT	There was no element with the ID.

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 function should not modify *pRaster.

◆ raster_purge

size_t(* HVD_cache_fns::raster_purge) (HVD_cache *cache, void *store, const uint8 id[16], void *hraster, HVD_recovery_reason reason, size_t *recover)

A function to compress or purge data from rasters when running low on cache memory. This is called for each raster attached to an element. If not enough memory can be recovered by purging the top candidate elements, they will be released.

This method is optional. Not all HVD cache implementations support data compression or purging.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster() or found using HVD_cache_fns::raster_find().
[in]	reason	The reason for recovering raster memory, passed through from HVD_cache_recover() or the internal purge. This parameter may be used to exclude rasters from compression or writing to storage if they cannot be represented in less space in the types of memory or storage specified by this reason.
[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.

◆ raster_release

void(* HVD_cache_fns::raster_release) (HVD_cache *cache, void *store, const uint8 id[16], void *hraster)

A function to call when an element with attached rasters is destroyed. This is called for each non-NULL raster attached to the element.

This method must be present to be able to instantiate an HVD cache using these functions.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of the element which the raster handle was attached to.
[in]	hraster	A raster handle previously passed to HVD_element_add_raster().

◆ recovery_filter

HqBool(* HVD_cache_fns::recovery_filter) (HVD_cache *cache, void *store, const uint8 id[16], HVD_recovery_reason reason)

A function to filter rasters to those suitable for compression or eviction when running low on memory. If this parameter is NULL, then all elements and rasters will be considered eligible for all low memory calls.

This method is optional. Not all cache implementations support data compression or purging.

Parameters

[in]	cache	The HVD cache instance containing element id.
[in]	store	The HVD element store implementation for cache.
[in]	id	The ID of 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.

◆ store_create

HVD_result(* HVD_cache_fns::store_create) (const HVD_cache_params *params, HVD_cache *cache, void **ppStore)

Create an element store for a new HVD element cache.

An HVD element cache associates HVD element IDs with HVD element data: the HVD element state (see HVD_element_state), the extent of the HVD element, and the rasters associated with the HVD element. The implementation of the element store is managed separately from the HVD element cache because the element store may be local to a single RIP, shared across a Scalable RIP or a machine, shared across a RIP farm, or even hosted in another process. Each of these methods of storing element data requires a separate implementation.

Parameters

[in]	params	The parameters for this HVD cache instance.
[in]	cache	The HVD cache instance being created.
[out]	ppStore	A location to put the element store pointer.

Return values

HVD_SUCCESS	The element store was created successfully, and a handle was stored in ppStore. If this function succeeds, HVD_cache_destroy() must be called to destroy it when the connection is disconnected.
HVD_ERROR_INVALID_PARAMS	The element store could not be created because the parameters were invalid.
HVD_ERROR_NO_MEMORY	The element store 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.

◆ store_destroy

void(* HVD_cache_fns::store_destroy) (HVD_cache *cache, void **ppStore, HqBool reusable, HVD_destroy_reason reason)

Destroy an HVD element store, after the last local reference to an HVD cache instance is released.

Even though the last local reference to a cache instance has been released, the HVD element store implementation may wish to defer the destruction of the store to a later point, if the store could still be referenced from another Farm RIP in a Scalable RIP. In this case, the element store implementation is responsible for eventual destruction of the element store.

Parameters

[in]	cache	The HVD cache instance being destroyed.
[in,out]	ppStore	A location containing the element store associated with cache. On exit, ppStore should be set to `NULL` if the element store was destroyed. The element store must be destroyed if the reason* parameter is not HVD_DESTROY_NORMAL, but it may be retained for future jobs if reason is HVD_DESTROY_NORMAL.
[in]	reusable	Is this cache reusable across jobs?
[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.

◆ store_purge

HqBool(* HVD_cache_fns::store_purge) (HVD_cache *cache, void *store, HVD_recovery_reason reason, size_t *recover, HVD_cache_policy cache_policy)

Recover an amount of memory from an element store.

Parameters

[in]	cache	The HVD cache instance to purge.
[in]	store	The HVD element store implementation for cache.
[in]	reason	The reason for the recovery operation, and implicitly the type of memory to be recovered.
[in,out]	recover	A pointer to the amount of memory remaining to be recovered. The method should update *recover on exit.
[in]	cache_policy	The cache policy used to select objects to recover.

Return values

TRUE	The store has, or may have elements in it, including non-recoverable elements.
FALSE	The store is empty. This is used to determine whether the store should be destroyed, and so should only be returned if the store is known to be empty.

This method may be called from arbitrary threads, including recursive calls for low memory recovery during a memory allocation. It is the implementation's responsibility to ensure mutual exclusion between methods. Since this method can be called during memory allocation, it is strongly recommended that mutual exclusion in this method should use trylocks.

◆ store_size

HqBool(* HVD_cache_fns::store_size) (HVD_cache *cache, void *store, HVD_recovery_reason reason, size_t *total)

Add the amount of recoverable memory in an element store to a total size.

Parameters

[in]	cache	The HVD cache instance to return the size of.
[in]	store	The HVD element store implementation for cache.
[in]	reason	The reason for the recovery operation, and implicitly the type(s) of memory to be recovered.
[in,out]	total	A pointer to the estimated amount of memory currently recoverable. This method should only increase this total.

Return values

TRUE	The store has, or may have elements in it, including non-recoverable elements.
FALSE	The store is empty. This is used to determine whether the store should be destroyed, and so should only be returned if the store is known to be empty.

This method may use an inexact estimate of the total size of elements in the store. If reason is HVD_COUNT_ALL, the total memory estimate is used to determine if the cache size limit is exceeded.

This method may be called from arbitrary threads, including recursive calls for low memory recovery during a memory allocation. It is the implementation's responsibility to ensure mutual exclusion between methods. Since this method can be called during memory allocation, it is strongly recommended that mutual exclusion in this method should use trylocks.

The documentation for this struct was generated from the following file:

lib/interface/hvdcache.h

Data Fields

Detailed Description

Field Documentation

◆ element_add

◆ element_add_raster

◆ element_has_rasters

◆ element_hits

◆ element_pending

◆ element_query_lock

◆ element_unlock

◆ raster_find

◆ raster_purge

◆ raster_release

◆ recovery_filter

◆ store_create

◆ store_destroy

◆ store_purge

◆ store_size