Storage and Backing Map

Cache layers

Partitioned (Distributed) cache service in Coherence has three distinct layers:

Client View
Storage Manager
Backing Map

The Client View represents a virtual layer that provides access to the underlying partitioned data. Access to this tier is provided via the ${xhtml} interface. In this layer you can also create synthetic data structures such as ${xhtml} or ${xhtml}.

The Storage Manager is the server-side tier that is responsible for processing cache-related requests from the client tier. It manages the data structures that hold the actual cache data (primary and backup copies) and information about locks, event listeners, map triggers etc.

The Backing Map is the server-side data structure that holds actual data.

Coherence 3.x allows users configure a number of out-of-the-box backing map implementations as well as custom ones. Basically, the only constraint that all these Map implementation have to be aware of, is the understanding that the Storage Manager provides all keys and values in internal (Binary) format. To deal with conversions of that internal data to and from an Object format, the Storage Manager can supply Backing Map implementations with a ${xhtml} reference.

Operations

There are number of operation types performed against the Backing Map:

Natural access and update operations caused by the application usage. For example, NamedCache.get() call naturally causes a Map.get() call on a corresponding BackingMap; NamedCache.invoke() call may cause a sequence of Map.get() followed by the Map.put(), NamedCache.keySet(filter) call may cause an Map.entrySet().iterator() loop, and so on.
Remove operations caused by the time-based expiry or the size-based eviction. For example, a NamedCache.get() or NamedCache.size() call from the client tier could cause a Map.remove() call due to an entry expiry timeout; or NamedCache.put() call causing a number of Map.remove() calls (for different keys) caused by the total amount data in a backing map reaching the configured high water-mark value.
Insert operations caused by a CacheStore.load() operation (for backing maps configured with read-through or read-ahead features)
Synthetic access and updates caused by the partition distribution (which in turn could be caused by cluster nodes fail-over or fail-back). In this case, without any application tier call, a number of entries could be inserted or removed from the backing map.

Component Encapsulation

Capacity Planning

Depending on the actual implementation, the Backing Map stores the cache data in one of the following ways:

On-heap memory
Off-heap memory
Disk (memory-mapped files or in-process DB)
Combination of any of the above

Keeping data in memory naturally provides dramatically smaller access and update latencies and is most commonly used.

More often than not, applications need to ensure that the total amount of data placed into the data grid does not exceed some predetermined amount of memory. It could be done either directly by the application tier logic or automatically using size- or expiry-based eviction. Quite naturally, the total amount of data held in a Coherence cache is equal to the sum of data volume in all corresponding backing maps (one per each cluster node that runs the corresponding partitioned cache service in a storage enabled mode).

Consider following cache configuration excerpts:

The backing map above is an instance of ${xhtml} and does not have any pre-determined size constraints and has to be controlled explicitly. Failure to do so could cause the JVM to go out-of-memory.

This backing map is also a ${xhtml} and has a capacity limit of 100MB. As the total amount of data held by this backing map exceeds that high watermark, some entries will be removed from the backing map, bringing the volume down to the low watermark value ("low-units" configuration element, witch defaults to 75% of the "high-units"). The choice of the removed entries will be based on the LRU (Least Recently Used) eviction policy. Other options are LFU (Least Frequently Used) and Hybrid (a combination of the LRU and LFU). The value of "high-units" is limited to 2GB. To overcome that limitation (but maintain backward compatibility) Coherence 3.5 introduced a "unit-factor" element. For example, the "high-units" value of 8192 with a "unit-factor" of 1048576 will result in a high watermark value of 8GB (see a configuration excerpt below).

This backing map will automatically evict any entries that were not updated for more than an hour. Note, that such an eviction is a "lazy" one and can happen any time after an hour since the last update happens; the only guarantee Coherence provides is that entries more than one hour old value will not be returned to a caller.

This backing map is an instance of ${xhtml} which stores values in the extended (nio) memory and has a capacity limit of 100MB (100*1048576). Quite naturally, you would configure a backup storage for this cache being "off-heap" (or "file-mapped"):

Partitioned Backing Maps

Prior to Coherence 3.5, a backing map would contain entries for all partitions owned by the corresponding node. (During partition transfer, it could also hold "in flight" entries that from the clients' perspective are temporarily not owned by anyone).

Coherence 3.5 introduced a concept of partitioned backing map, which is basically a multiplexer of actual Map implementations, each of which would contain only entries that belong to the same partition.

To configure it, all you need is to add a "partitioned" element with a value of "true".

This backing map is an instance of ${xhtml}, with individual partition holding maps being instances of ${xhtml} that each store values in the extended (nio) memory. The individual nio buffers have a limit of 50MB, while the backing map as whole has a capacity limit of 8GBB (8192*1048576). Again, you would need to configure a backup storage for this cache being "off-heap" or "file-mapped".