Class ConcurrentKeyLock<K,V>

java.lang.Object
java.util.AbstractMap<K,V>
com.tangosol.util.ConcurrentKeyLock<K,V>
Type Parameters:
K - the key type
V - the value type
All Implemented Interfaces:
ConcurrentMap<K,V>, Map<K,V>
public class ConcurrentKeyLock<K,V> extends AbstractMap<K,V> implements ConcurrentMap<K,V>
A ConcurrentMap implementation backed by a ConcurrentHashMap that provides per-key reentrant locking without intrinsic monitors.

The map operations are delegated to an internal ConcurrentHashMap; the resource-control-map role only relies on the lock API.

Since:
26.04
Author:
Aleks Seovic 2026.04.10

  • Field Details

  • Constructor Details

  • Method Details

    • lock

      public boolean lock(Object oKey)
      Description copied from interface: ConcurrentMap
      Attempt to lock the specified item and return immediately.

      This method behaves exactly as if it simply performs the call lock(oKey, 0).

      Specified by:
      lock in interface ConcurrentMap<K,V>
      Parameters:
      oKey - key being locked
      Returns:
      true if the item was successfully locked; false otherwise

    • lock

      public boolean lock(Object oKey, long cWait)
      Description copied from interface: ConcurrentMap
      Attempt to lock the specified item within the specified period of time.

      The item doesn't have to exist to be locked. While the item is locked there is known to be a lock holder which has an exclusive right to modify (calling put and remove methods) that item.

      Lock holder is an abstract concept that depends on the ConcurrentMap implementation. For example, holder could be a cluster member or a thread (or both).

      Locking strategy may vary for concrete implementations as well. Lock could have an expiration time (this lock is sometimes called a "lease") or be held indefinitely (until the lock holder terminates).

      Some implementations may allow the entire map to be locked. If the map is locked in such a way, then only a lock holder is allowed to perform any of the "put" or "remove" operations. Pass the special constant ConcurrentMap.LOCK_ALL as the oKey parameter to indicate the map lock.

      Specified by:
      lock in interface ConcurrentMap<K,V>
      Parameters:
      oKey - key being locked
      cWait - the number of milliseconds to continue trying to obtain a lock; pass zero to return immediately; pass -1 to block the calling thread until the lock could be obtained
      Returns:
      true if the item was successfully locked within the specified time; false otherwise

    • unlock

      public boolean unlock(Object oKey)
      Description copied from interface: ConcurrentMap
      Unlock the specified item. The item doesn't have to exist to be unlocked. If the item is currently locked, only the holder of the lock could successfully unlock it.
      Specified by:
      unlock in interface ConcurrentMap<K,V>
      Parameters:
      oKey - key being unlocked
      Returns:
      true if the item was successfully unlocked; false otherwise

    • entrySet

      public Set<Map.Entry<K,V>> entrySet()
      Specified by:
      entrySet in interface Map<K,V>
      Specified by:
      entrySet in class AbstractMap<K,V>

    • put

      public V put(K key, V value)
      Description copied from interface: ConcurrentMap
      Associates the specified value with the specified key in this map (optional operation). If the map previously contained a mapping for this key, the old value is replaced.

      Some implementations will attempt to obtain a lock for the key (if necessary) before proceeding with the put operation. For such implementations, the specified item has to be either already locked or able to be locked for this operation to succeed.

      Specified by:
      put in interface ConcurrentMap<K,V>
      Specified by:
      put in interface Map<K,V>
      Overrides:
      put in class AbstractMap<K,V>
      Parameters:
      key - key with which the specified value is to be associated
      value - value to be associated with the specified key
      Returns:
      previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values

    • get

      public V get(Object key)
      Description copied from interface: ConcurrentMap
      Returns the value to which this map maps the specified key. Returns null if the map contains no mapping for this key. A return value of null does not necessarily indicate that the map contains no mapping for the key; it's also possible that the map explicitly maps the key to null. The containsKey operation may be used to distinguish these two cases.
      Specified by:
      get in interface ConcurrentMap<K,V>
      Specified by:
      get in interface Map<K,V>
      Overrides:
      get in class AbstractMap<K,V>
      Parameters:
      key - key whose associated value is to be returned
      Returns:
      the value to which this map maps the specified key, or null if the map contains no mapping for this key
      See Also:

    • remove

      public V remove(Object key)
      Description copied from interface: ConcurrentMap
      Removes the mapping for this key from this map if present (optional operation).

      Some implementations will attempt to obtain a lock for the key (if necessary) before proceeding with the remove operation. For such implementations, the specified item has to be either already locked or able to be locked for this operation to succeed.

      Specified by:
      remove in interface ConcurrentMap<K,V>
      Specified by:
      remove in interface Map<K,V>
      Overrides:
      remove in class AbstractMap<K,V>
      Parameters:
      key - key whose mapping is to be removed from the map
      Returns:
      previous value associated with specified key, or null if there was no mapping for key. A null return can also indicate that the map previously associated null with the specified key, if the implementation supports null values

    • containsKey

      public boolean containsKey(Object key)
      Description copied from interface: ConcurrentMap
      Returns true if this map contains a mapping for the specified key.
      Specified by:
      containsKey in interface ConcurrentMap<K,V>
      Specified by:
      containsKey in interface Map<K,V>
      Overrides:
      containsKey in class AbstractMap<K,V>
      Parameters:
      key - key whose presence in this map is to be tested
      Returns:
      true if this map contains a mapping for the specified key

    • containsValue

      public boolean containsValue(Object value)
      Description copied from interface: ConcurrentMap
      Returns true if this map maps one or more keys to the specified value. More formally, returns true if and only if this map contains at least one mapping to a value v such that (value==null ? v==null : value.equals(v)). This operation will probably require time linear in the map size for most implementations of the ConcurrentMap interface.
      Specified by:
      containsValue in interface ConcurrentMap<K,V>
      Specified by:
      containsValue in interface Map<K,V>
      Overrides:
      containsValue in class AbstractMap<K,V>
      Parameters:
      value - value whose presence in this map is to be tested
      Returns:
      true if this map maps one or more keys to the specified value

    • size

      public int size()
      Description copied from interface: ConcurrentMap
      Returns the number of key-value mappings in this map. Note that this number does not include the items that were locked but didn't have corresponding map entries.
      Specified by:
      size in interface ConcurrentMap<K,V>
      Specified by:
      size in interface Map<K,V>
      Overrides:
      size in class AbstractMap<K,V>
      Returns:
      the number of key-value mappings in this map

    • isEmpty

      public boolean isEmpty()
      Description copied from interface: ConcurrentMap
      Returns true if this map contains no key-value mappings. Note that the map could have some items locked and be empty at the same time.
      Specified by:
      isEmpty in interface ConcurrentMap<K,V>
      Specified by:
      isEmpty in interface Map<K,V>
      Overrides:
      isEmpty in class AbstractMap<K,V>
      Returns:
      true if this map contains no key-value mappings

    • putAll

      public void putAll(Map<? extends K, ? extends V> map)
      Description copied from interface: ConcurrentMap
      Copies all of the mappings from the specified map to this map (optional operation). These mappings will replace any mappings that this map had for any of the keys currently in the specified map.
      Specified by:
      putAll in interface ConcurrentMap<K,V>
      Specified by:
      putAll in interface Map<K,V>
      Overrides:
      putAll in class AbstractMap<K,V>
      Parameters:
      map - Mappings to be stored in this map

    • clear

      public void clear()
      Description copied from interface: ConcurrentMap
      Removes all mappings from this map.

      Some implementations will attempt to lock the entire map (if necessary) before proceeding with the clear operation. For such implementations, the entire map has to be either already locked or able to be locked for this operation to succeed.

      Specified by:
      clear in interface ConcurrentMap<K,V>
      Specified by:
      clear in interface Map<K,V>
      Overrides:
      clear in class AbstractMap<K,V>

    • lockAll

      protected boolean lockAll(long cWait)
      Attempt to acquire the global write lock.
      Parameters:
      cWait - the wait timeout in millis
      Returns:
      true if the write lock was acquired
      Implementation Note:
      Callers must not attempt to upgrade from a held per-key lock to ConcurrentMap.LOCK_ALL on the same thread; the underlying ReentrantReadWriteLock does not support read-to-write upgrades.

    • unlockAll

      protected boolean unlockAll()
      Release the global write lock.
      Returns:
      true if the current thread held the global write lock

    • acquireReadLock

      protected boolean acquireReadLock(long cWait, long ldtLimit)
      Acquire the global read lock.
      Parameters:
      cWait - the wait timeout in millis
      ldtLimit - the absolute deadline in nanos if timed
      Returns:
      true if the read lock was acquired

    • releaseReadLock

      protected void releaseReadLock()
      Release one per-key-lock hold against the global read lock.

    • remainingNanos

      protected long remainingNanos(long cWait, long ldtLimit)
      Return the remaining time in nanos.
      Parameters:
      cWait - the original wait in millis
      ldtLimit - the absolute deadline in nanos
      Returns:
      the remaining time in nanos

    • retainLockEntry

      protected ConcurrentKeyLock.LockEntry retainLockEntry(K key)
      Retain the lock entry for the specified key.
      Parameters:
      key - the key
      Returns:
      the retained lock entry

    • releaseLockEntry

      protected void releaseLockEntry(K key, ConcurrentKeyLock.LockEntry entry)
      Release the retained reference for the specified key.
      Parameters:
      key - the key
      entry - the retained lock entry