Package com.tangosol.util

Class MultiBinaryLongMap

java.lang.Object
com.tangosol.util.MultiBinaryLongMap
public class MultiBinaryLongMap extends Object
A data structure that represents a series of BinaryLongMap instances. The first (or "primary") instance is the control instance, in that only it defines the key set, i.e. a Binary key can only be added to or removed from the primary instance. Additional instances of BinaryLongMap can be obtained from the MultiBinaryLongMap, but these instances are constrained by the key set of the primary BinaryLongMap instance; it is illegal for one of these instances to add a key that does not exist in the primary instance, and removing a key simply sets the associated value to zero (which has the effect of the key appearing to have been removed).

Since additions or removals from the primary instance has an effect on all other instances, it is possible to listen to changes in the primary instance's key set by implementing the BinaryLongMapListener interface. This listener interface provides notifications of additions (after they happen), removals (before they happen), and clear operations (both before and after they happen). By using this interface, it is possible for consumers of the additional BinaryLongMap instances to keep in sync with the changes that are occurring to the primary BinaryLongMap instance.

Author:
cp, rhl 2012-08-07

  • Field Details

    • f_tree

      protected final BinaryRadixTree f_tree
      The underlying storage for the keys and handles.

    • f_storage

      protected final MultiBinaryLongMap.LongStorage f_storage
      The underlying storage for the values.

    • f_blmPrimary

      protected final MultiBinaryLongMap.PrimaryBinaryLongMap f_blmPrimary
      The primary BinaryLongMap instance.

    • f_holderLeftover

      protected final MultiBinaryLongMap.LeftoverLongMapHolder f_holderLeftover
      The MaskedLongMapHolder representing the "leftover" space in the primary BinaryLongMap.

    • f_rwLockMaster

      protected final ReentrantReadWriteLock f_rwLockMaster
      The read/write lock for concurrency control for the BinaryRadixTree.

    • f_listDelegates

      protected final ArrayList f_listDelegates
      The list of delegates (either a DelegateBLM, or a MaskedLongMapHolder) indexed by the free

  • Constructor Details

    • MultiBinaryLongMap

      public MultiBinaryLongMap()
      Construct a MultiBinaryLongMap.

    • MultiBinaryLongMap

      public MultiBinaryLongMap(ReentrantReadWriteLock lock)
      Construct a MultiBinaryLongMap.
      Parameters:
      lock - the ReentrantReadWriteLock to use for thread safety; if one is not provided, then one will be created

  • Method Details

    • getPrimaryBinaryLongMap

      public MultiBinaryLongMap.PrimaryBinaryLongMap getPrimaryBinaryLongMap()
      Obtain a reference to the primary BinaryLongMap instance.

      The returned BinaryLongMap is thread-safe.

      Returns:
      the primary BinaryLongMap instance, which "owns" the keys that are represented in all of the BinaryLongMap instances, and thus can add or remove keys

    • createBinaryLongMap

      public BinaryLongMap createBinaryLongMap()
      Create a new BinaryLongMap that can be used to manage values for the set of keys present in the primary BinaryLongMap instance.

      The returned BinaryLongMap is thread-safe.

      Returns:
      a new BinaryLongMap instance that manages a mapping between Binary keys and long values

    • createBinaryLongMapInternal

      protected MultiBinaryLongMap.DelegatingBinaryLongMap createBinaryLongMapInternal()
      Helper method to create a new delegating BinaryLongMap. This method does not return the created BinaryLongMap as a SafeBinaryLongMap and requires that the caller holds the master exclusive lock for the MultiBinaryLongMap.
      Returns:
      a new delegating BinaryLongMap

    • createBitMap

      public BinaryLongMap createBitMap(int cBits)
      Create a new BinaryLongMap that can be used to manage numeric values of the specified bit-width for the set of keys present in the primary BinaryLongMap instance. Values inserted into the returned BinaryLongMap must fit within the specified number of bits (logically having the range of: -(1 << (cBits - 1) through (1 << (cBits - 1))) - 1. Values returned from the resulting map will be sign-extended to the long data-type and it is the responsibility of calling code intending to use the map to store unsigned values to adjust/mask the sign accordingly.

      The returned BinaryLongMap is thread-safe.

      Parameters:
      cBits - the bit-width of values
      Returns:
      a new BinaryLongMap instance that manages a mapping between Binary keys and numeric values of the specified bit width

    • createBinaryIntMap

      public BinaryLongMap createBinaryIntMap()
      Create a new BinaryLongMap that can be used to manage int (not long) values for the set of keys present in the primary BinaryLongMap instance. Values inserted into the returned BinaryLongMap must fit within the 32-bits (logically having the range of the int datatype. More formally, the value logically inserted into the map is given by: (long) ((int) (lValue & 0xFFFFFFFFL)). Values returned from the resulting map will be sign-extended to the long data-type and it is the responsibility of calling code intending to use the map to store unsigned values to adjust/mask the sign accordingly.

      The returned BinaryLongMap is thread-safe.

      Returns:
      a new BinaryLongMap instance that manages a mapping between Binary keys and int values

    • releaseMap

      public void releaseMap(BinaryLongMap blm)
      Release one of the maps previously returned from either createBinaryLongMap(), createBinaryIntMap() or createBitMap(int). It is illegal to pass an instance not created by this MultiBinaryLongMap, or to pass the primary BinaryLongMap instance.
      Parameters:
      blm - a BinaryLongMap instance previously created by this MultiBinaryLongMap

    • releaseMapInternal

      protected void releaseMapInternal(BinaryLongMap blm)
      Helper method for releasing a BinaryLongMap created by this MultiBinaryLongMap. The caller is responsible for unwrapping any "safe" wrappers around the BinaryLongMap that is being released, as well as holding the master exclusive lock for this MultiBinaryLongMap.
      Parameters:
      blm - the BinaryLongMap to be released

    • addListener

      public void addListener(MultiBinaryLongMap.BinaryLongMapListener listener)
      Add the specified listener to listen to changes that occur to the MultiBinaryLongMap's primary BinaryLongMap.
      Parameters:
      listener - the listener to add

    • removeListener

      public void removeListener(MultiBinaryLongMap.BinaryLongMapListener listener)
      Remove the specified listener from listening to changes that occur to the MultiBinaryLongMap's primary BinaryLongMap.
      Parameters:
      listener - the listener to remove

    • decodeSlot

      protected static int decodeSlot(long l)
      Extract a slot index from a long that was stored in a BinaryLongMap.
      Parameters:
      l - the long value stored in the BinaryLongMap
      Returns:
      the slot index to use with a LongStorage

    • decodeRemainder

      protected static int decodeRemainder(long l)
      Extract the "remainder" portion (the portion not encoding the slot) from the specified long that was stored in a BinaryLongMap.
      Parameters:
      l - the long value stored in the BinaryLongMap
      Returns:
      the remainder portion of the specified long value

    • encodeSlot

      protected static long encodeSlot(long l, int iSlot)
      Encode a slot index as a long that can be stored in a BinaryLongMap. Only the least significant 32 bits are used.
      Parameters:
      l - the long value stored in the BinaryLongMap
      iSlot - the slot index for a LongStorage
      Returns:
      the long to store in the BinaryLongMap

    • encodeRemainder

      protected static long encodeRemainder(long l, int iRemainder)
      Encode a 32-bit "remainder" value as a long that can be stored in a BinaryLongMap.
      Parameters:
      l - the long value stored in the BinaryLongMap
      iRemainder - the 32-bit remainder to encode
      Returns:
      the long to store in the BinaryLongMap

    • ensureSafePredicate

      protected static MultiBinaryLongMap.SafePredicate ensureSafePredicate(Predicate<BinaryLongMap.Entry> predicate)
      Return a SafePredicate based on the specified predicate implementation.
      Parameters:
      predicate - the predicate
      Returns:
      a SafePredicate

    • ensureSafeVisitor

      protected static MultiBinaryLongMap.SafeEntryVisitor ensureSafeVisitor(BinaryLongMap blm, BinaryLongMap.EntryVisitor visitor)
      Return a SafeEntryVisitor based on the specified visitor implementation.
      Parameters:
      visitor - the visitor
      Returns:
      a SafeEntryVisitor