Package org.infinispan.container.offheap

Class OffHeapConcurrentMap

java.lang.Object
org.infinispan.container.offheap.OffHeapConcurrentMap
All Implemented Interfaces:
AutoCloseable, ConcurrentMap<WrappedBytes,InternalCacheEntry<WrappedBytes,WrappedBytes>>, Map<WrappedBytes,InternalCacheEntry<WrappedBytes,WrappedBytes>>, PeekableTouchableMap<WrappedBytes,WrappedBytes>
public class OffHeapConcurrentMap extends Object implements ConcurrentMap<WrappedBytes,InternalCacheEntry<WrappedBytes,WrappedBytes>>, PeekableTouchableMap<WrappedBytes,WrappedBytes>, AutoCloseable
A ConcurrentMap implementation that stores the keys and values off the JVM heap in native heap. This map does not permit null for key or values.

The key and value are limited to objects that implement the WrappedBytes interface. Currently this map only allows for implementations that always return a backing array via the WrappedBytes.getBytes() method.

For reference here is a list of commonly used terms:

  • bucket: Can store multiple entries (normally via a forward only list)
  • memory lookup: Stores an array of buckets - used primarily to lookup the location a key would be
  • lock region: The number of lock regions is fixed, and each region has bucket count / lock count buckets.

This implementation provides constant-time performance for the basic operations (get, put, remove and compute), assuming the hash function disperses the elements properly among the buckets. Iteration over collection views requires time proportional to the number of buckets plus its size (the number of key-value mappings). This map always assumes a load factor of .75 that is not changeable.

A map must be started after creating to create the initial memory lookup, which is also store in the native heap. When the size of the map reaches the load factor, that is .75 times the capacity, the map will attempt to resize by increasing its internal memory lookup to have an array of buckets twice as big. Normal operations can still proceed during this, allowing for minimal downtime during a resize.

This map is created assuming some knowledge of expiration in the Infinispan system. Thus operations that do not expose this information via its APIs are not supported. These methods are keySet, containsKey and containsValue.

This map guarantees consistency under concurrent read ands writes through a StripedLock where each ReadWriteLock instance protects an equivalent region of buckets in the underlying memory lookup. Read operations, that is ones that only acquire the read lock for their specific lock region, are (get and peek). Iteration on a returned entrySet or value collection will acquire only a single read lock at a time while inspecting a given lock region for a valid value. Write operations, ones that acquire the write lock for the lock region, are (put, remove, replace, compute. A clear will acquire all write locks when invoked. This allows the clear to also resize the map down to the initial size.

When this map is constructed it is also possible to provide an OffHeapConcurrentMap.EntryListener that is invoked when various operations are performed in the map. Note that the various modification callbacks MUST free the old address, or else a memory leak will occur. Please see the various methods for clarification on these methods.

Since this map is based on holding references to memory that lives outside of the scope of the JVM garbage collector users need to ensure they properly invoke the close() when the map is no longer in use to properly free all allocated native memory.

Since:
9.4
Author:
wburns