Pinning Data

Without pinning, expired cache entries can be flushed and eventually evicted, and even most non-expired elements can also be flushed and evicted as well, if resource limitations are reached. Pinning gives per-cache control over whether data can be evicted from BigMemory Max.

Data that should remain in memory can be pinned. You cannot pin individual entries, only an entire cache. As described in the following topics, there are two types of pinning, depending upon whether the pinning configuration should take precedence over resource constraints or the other way around.

Entire caches can be pinned using the pinning element in the Ehcache configuration. This element has a required attribute (store) to specify how the pinning will be accomplished.

The store attribute can have either of the following values:

inCache – Data is pinned in the cache, in any tier in which cache data is stored. The tier is chosen based on performance-enhancing efficiency algorithms. Unexpired entries can never be evicted.

localMemory – Data is pinned to the memory store or the off-heap store. Entries are evicted only in the event that the store's configured size is exceeded. Updated copies of invalidated elements are faulted in from the server, a behavior you can override by setting the Terracotta property l1.servermapmanager.faultInvalidatedPinnedEntries to false.

For example, the following cache is configured to pin its entries:

The following cache is configured to pin its entries to heap or off-heap only:

The interaction of the pinning configuration with the cache sizing configuration depends upon which pinning option is used.

For inCache pinning, the pinning setting takes priority over the configured cache size. Elements resident in a cache with this pinning option cannot be evicted if they have not expired. This type of pinned cache is not eligible for eviction at all, and maxEntriesInCache should not be configured for this cache.

Important:
Potentially, pinned caches could grow to an unlimited size. Caches should never be pinned unless they are designed to hold a limited amount of data (such as reference data) or their usage and expiration characteristics are understood well enough to conclude that they cannot cause errors.

For localMemory pinning, the configured cache size takes priority over the pinning setting. localMemory pinning should be used for optimization, to keep data in heap or off-heap memory, unless or until the tier becomes too full. If the number of entries surpasses the configured size, entries will be evicted. For example, in the following cache the maxEntriesLocalHeap and maxBytesLocalOffHeap settings override the pinning configuration. (Off-heap storage is only available in the BigMemory products.)

Pinning as a setting exists in the local Ehcache client (L1) memory. It is never distributed in the cluster. In case the pinned cache is bulk loaded, the pinned data is removed from the L1 and will be faulted back in from the Terracotta Server Array.

Pinning achieved programmatically will not be persisted — after a restart the pinned entries are no longer pinned. Pinning is also lost when an L1 rejoins a cluster. Cache pinning in configuration is reinstated with the configuration file.

To unpin all of a cache's pinned entries, clear the cache. Specific entries can be removed from a cache using Cache.remove(). To empty the cache, Cache.removeAll(). If the cache itself is removed (Cache.dispose() or CacheManager.removeCache()), then any data still remaining in the cache is also removed locally. However, that remaining data is not removed from the Terracotta Server Array or disk (if localRestartable).