# IBM Visualization Data Explorer Programmer's Reference

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]

## 13.5 Cache

The look-aside cache service stores the results of computations for later use. Each cache entry is uniquely identified by a string function name, an integer key (which the executive uses to store multiple outputs for a single module), the number of input parameters, and the set of input parameter values.

The input parameters and the Object to be cached must be Data Explorer Objects.

Associating data with a cache entry. User data not already in the form of an Object can be associated with a cache entry by means of a Private Object (see 12.5 , "Private Class"), encapsulating the data in an object. To associate more than one Object with a cache entry, use a Group to contain the Objects.

Losing a cache entry. Cache entries are subject to deletion without notice (e.g., when the system reclaims memory). The relative cost of creating an entry (which must be specified when the entry is created) may be taken into account when deleting Objects from the cache. If an estimate is not readily available, specify zero (0). Specifying `CACHE_PERMANENT` as the cost prevents the entry from being deleted during memory reclamation.

Object reference counts and the cache. It is important to be aware of the following: The system uses the cache to store intermediate results from modules. Thus inputs to modules often come from the cache. However:

- Once you have a pointer to a module's input, you can be sure it will not be deleted while you are processing it.
- If the input is a Group and you extract a member, that member will not be deleted while you are using it (because the Group will not be deleted).

However, Objects other than module inputs that are put into or retrieved from the cache behave differently: Once an Object is put in the cache, the system may delete it at any time to reclaim memory. This last has two consequences.

1. `DXGetCacheEntry()` returns an Object that is referenced so that it will not be deleted. Thus, you must delete the Object when you are finished using it:

           o = DXGetCacheEntry(...);
           ... use o ...
           DXDelete(o);

   Failure to do so will result in a memory leak, because the Object will always have an extra reference.

2. To continue using an Object after putting it in the cache, you must reference it before putting it there, and delete it when it is no longer needed:

           o = New...;
           DXReference(o);
           DXSetCacheEntry(..., o, ...);
           ... use o ...
           DXDelete(o);

   Conversely, if putting the Object in the cache is the last operation before the return, and if `o` is not visible outside the scope of the routine, no reference is necessary:

           o = New...;
           ... use o ...
           DXSetCacheEntry(..., o, ...);
           return ...;

   where the return statement does not return `o`.

Cache Routines

    #define CACHE_PERMANENT 1e32

`Object DXGetCacheEntry() Object DXGetCacheEntryV()` | Retrieve a cache entry. See DXGetCacheEntry, DXGetCacheEntryV.
`Error DXSetCacheEntry() Error DXSetCacheEntryV()` | Set a cache entry. See DXSetCacheEntry, DXSetCacheEntryV.
`Error DXFreeModuleId() Pointer DXGetModuleId()` | Get a unique identifier for each instance of a module. See DXFreeModuleId and DXGetModuleId.
`Error DXCompareModuleId()` | Returns OK if the two specified module identifiers are the same; otherwise returns ERROR. See DXCompareModuleId.
`Pointer DXCopyModuleId()` | Returns a pointer to a copy of the specified module identifier. See DXCopyModuleId.

[ Top of Page | Previous Page | Next Page | Table of Contents | Partial Table of Contents | Index ]
[Data Explorer Documentation | QuickStart Guide | User's Guide | User's Reference | Programmer's Reference | Installation and Configuration Guide ]

[Data Explorer Home Page]

[IBM Home Page | Order | Search | Contact IBM | Legal ]