Package org.infinispan.container.offheap

Class OffHeapConcurrentMap

java.lang.Object
org.infinispan.container.offheap.OffHeapConcurrentMap
All Implemented Interfaces:
AutoCloseable, ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>, Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>, PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>
public class OffHeapConcurrentMap extends Object implements ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>, PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.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

  • Field Details

  • Constructor Details

  • Method Details

    • touchKey

      public boolean touchKey(Object k, long currentTimeMillis)
      Description copied from interface: PeekableTouchableMap
      Touches the entry for the given key in this map. This method will update any recency timestamps for both expiration or eviction as needed.
      Specified by:
      touchKey in interface PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>
      Parameters:
      k - key to touch
      currentTimeMillis - the recency timestamp to set
      Returns:
      whether the entry was touched or not

    • touchAll

      public void touchAll(long currentTimeMillis)
      Description copied from interface: PeekableTouchableMap
      Touches all entries in the map setting the recency timestamps for both expiration eviction appropriately.
      Specified by:
      touchAll in interface PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>
      Parameters:
      currentTimeMillis - the recency timestamp to set

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • size

      public int size()
      Specified by:
      size in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • isEmpty

      public boolean isEmpty()
      Specified by:
      isEmpty in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • compute

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> compute(org.infinispan.commons.marshall.WrappedBytes key, BiFunction<? super org.infinispan.commons.marshall.WrappedBytes,? super InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>,? extends InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>> remappingFunction)
      Specified by:
      compute in interface ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>
      Specified by:
      compute in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • containsKey

      public boolean containsKey(Object key)
      Specified by:
      containsKey in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • containsValue

      public boolean containsValue(Object value)
      Specified by:
      containsValue in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • get

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> get(Object key)
      Specified by:
      get in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • peek

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> peek(Object key)
      Description copied from interface: PeekableTouchableMap
      Peaks at a value for the given key. Note that this does not update any expiration or eviction information when this is performed on the map, unlike the get method.
      Specified by:
      peek in interface PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>
      Parameters:
      key - The key to find the value for
      Returns:
      The value mapping to this key

    • putNoReturn

      public void putNoReturn(org.infinispan.commons.marshall.WrappedBytes key, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> value)
      Description copied from interface: PeekableTouchableMap
      Same as Map.put(Object, Object) except that the map is not required to return a value. This can be useful when retrieving a previous value may incur additional costs.

      Specified by:
      putNoReturn in interface PeekableTouchableMap<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>
      Parameters:
      key - key to insert for the value
      value - the value to insert into this map

    • put

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> put(org.infinispan.commons.marshall.WrappedBytes key, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> value)
      Specified by:
      put in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • remove

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> remove(Object key)
      Specified by:
      remove in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • putAll

      public void putAll(Map<? extends org.infinispan.commons.marshall.WrappedBytes,? extends InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>> m)
      Specified by:
      putAll in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • clear

      public void clear()
      Specified by:
      clear in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • putIfAbsent

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> putIfAbsent(org.infinispan.commons.marshall.WrappedBytes key, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> value)
      Specified by:
      putIfAbsent in interface ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>
      Specified by:
      putIfAbsent in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • remove

      public boolean remove(Object key, Object value)
      Specified by:
      remove in interface ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>
      Specified by:
      remove in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • replace

      public boolean replace(org.infinispan.commons.marshall.WrappedBytes key, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> oldValue, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> newValue)
      Specified by:
      replace in interface ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>
      Specified by:
      replace in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • replace

      public InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> replace(org.infinispan.commons.marshall.WrappedBytes key, InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes> value)
      Specified by:
      replace in interface ConcurrentMap<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>
      Specified by:
      replace in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • keySet

      public Set<org.infinispan.commons.marshall.WrappedBytes> keySet()
      Specified by:
      keySet in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • values

      public Collection<InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>> values()
      Specified by:
      values in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>

    • entrySet

      public Set<Map.Entry<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>> entrySet()
      Specified by:
      entrySet in interface Map<org.infinispan.commons.marshall.WrappedBytes,InternalCacheEntry<org.infinispan.commons.marshall.WrappedBytes,org.infinispan.commons.marshall.WrappedBytes>>