Adjusting the Retention Priority of Objects in Cache

A set of methods defined for the Process class enables you to adjust and interrogate the retention characteristics of an object in cache. The retention characteristics affect the relative priority of cached objects in respect to how long they are retained in cache.

When the object cache is full and a new object is to be copied into cache, one or more objects must be removed from the cache to make enough room. By default, the least-recently referenced object is selected for removal from cache.

The methods in the following subsections enable you to adjust this policy for selected objects in cache, by using a concept of lives. By default, an object has a single life. If it is selected to be removed from cache because it is the object that was least-recently accessed, it is removed because it has used its one life.

The Process class adjustObjectCachePriority and setObjectCachePriority methods allow the number of lives an object in cache has to be altered. When an object is a candidate to be removed from cache but its number of lives is greater than 1, the object is not removed from cache; instead its number of lives is decremented and it is treated as if it had just been referenced. It therefore remains in cache for an additional period.

You can therefore use the adjustObjectCachePriority and setObjectCachePriority methods to increase the number of lives of an object in cache, causing it to be retained longer in the object cache. This can suit objects that are repeatedly accessed but potentially have time gaps between accesses.

You can also use these methods to lower the number of lives for an object in cache; in particular, if you set the number of lives to zero (0), the object is removed from cache immediately. This suits objects that are accessed once only.

After being accessed, you can use the setObjectCachePriority method to set the lives of an object to zero (0) so that it is immediately removed from cache. This prevents objects that are not likely to be accessed again from filling the cache at the expense of other more-regularly accessed objects.

Although String Large Objects (slobs) and Binary Large Objects (blobs) are removed when the cache priority of an object is set to zero (0), exclusive collections are not removed and you must remove these individually, as shown in the following examples.

// remove obj1 from cache as well as its slobs and blobs, but not its 
// exclusive collections
process.setObjectCachePriority(obj1, 0);

// remove the exclusive collection obj2.allObj3s from cache and any of 
// its collection blocks
process.setObjectCachePriority(obj2.allObj3s, 0);

A process must use its own Process instance as the method receiver. Using any other Process instance raises exception 1265 (Environmental object operation is out of scope for process).

For details, see the following subsections.