Package com.tangosol.util

Class 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

    • Constructor Detail

      • 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 Detail

      • 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