IBM Visualization Data Explorer Programmer's Reference

DXSetCacheEntry, DXSetCacheEntryV

Function

Set a cache entry.

Syntax

#include <dx/dx.h>

Error DXSetCacheEntry(Object out, double cost,
char *function, int key, int n, ...)
Error DXSetCacheEntryV(Object out, double cost,
char *function, int key, int n, Object *in)

Functional Details

Create or alter a cache entry to store a reference to out. The cache entry is indexed by a key created from function, key, n, and the Objects in the Array in. The parameter function makes the key unique to the caller; key allows the caller to have multiple cache entries with the same function, and n and in allow the cache entry to be related to the Objects that were used to create it. Setting a cache entry to NULL removes the entry and deletes the Object.

The out parameter must be a Data Explorer Object. Private Objects may be used to store arbitrary user data in the cache.

The entry may be automatically deleted at any time because of memory constraints unless cost is set to a value equal to or greater than CACHE_PERMANENT.

Notes:

1. Because Data Explorer modules follow pure function semantics, the cache should not be used to store a state that affects the output of the module. A module must always be able to recreate the Object from the same set of inputs; the cache should be used only as an optimization tool.

2. On a multiprocessor machine, processor local information should not be stored in the cache, since its contents may be retrieved on another processor.

3. The cache is local to one machine and cannot be used to communicate information between modules on different machines when running in distributed mode.

Because Objects in the cache are candidates for deletion at any time, DXReference should be called before caching an Object if that Object is to be used later.

If you have called DXReference on the Object before putting it in the cache, call DXDelete when the Object is no longer being used; the latter call will not delete the Object from the cache. (To delete an Object from the cache, set the cache entry to NULL with DXSetCacheEntry.)

Return Value

Return OK or return NULL and set an error code.

See Also

DXDelete, DXGetCacheEntry, DXGetCacheEntryV, DXGetObjectTag, DXSetObjectTag, DXNewPrivate, DXReference

13.5 , "Cache".

[Data Explorer Home Page]