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
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
MultiBinaryLongMap.AbstractDelegateBinaryLongMap
Abstract base class for BinaryLongMap implementations that delegate the key and value storage to the MultiBinaryLongMap.static interface
MultiBinaryLongMap.BinaryLongMapListener
A listener that allows the owner of one of the delegating maps to respond to changes in the key set made by an owner of another delegating map.protected static class
MultiBinaryLongMap.ChainedLock
A ChainedLock is aLock
implementation that represents a composition of two component locks, parent and child.static class
MultiBinaryLongMap.DelegatingBinaryLongMap
An implementation of BinaryLongMap that uses another BinaryLongMap to store its keys and one index of a LongStorage to store its values.class
MultiBinaryLongMap.LeftoverLongMapHolder
LeftoverLongMapHolder is the MaskedLongMapHolder implementation that is backed by the "real" key tree itself.protected static class
MultiBinaryLongMap.LongStorage
An internal data structure for managing elastic storage of multi-dimensional data; basically, it is a two-dimensional array of rows and columns that can be grown in either dimension, but is optimized specifically for the addition and removal of rows.static class
MultiBinaryLongMap.MaskedBinaryLongMap
MaskedBinaryLongMap is a BinaryLongMap which represents a mapping from a Binary to a fixed-bit-width numeric value (though exposed as a long datatype), based on an underlying BinaryLongMap.protected static class
MultiBinaryLongMap.MaskedLongMapHolder
MaskedLongMapHolder is used to produceMultiBinaryLongMap.MaskedBinaryLongMap
instances backed by a shared BinaryLongMap.class
MultiBinaryLongMap.PrimaryBinaryLongMap
A BinaryLongMap implementation that logically represents the "primary" BinaryLongMap of the containing MultiBinaryLongMap.static class
MultiBinaryLongMap.SafeBinaryLongMap
The SafeBinaryLongMap is a BinaryLongMap implementation that wraps an underlying BinaryLongMap in order to add thread safety.protected static class
MultiBinaryLongMap.SafeEntry
SafeEntry is an immutableBinaryLongMap.Entry
implementation that exposes the logical contents of an underlying Entry in a way that is safe from mutations or being held as a reference.static interface
MultiBinaryLongMap.SafeEntryVisitor
SafeEntryVisitor is a marker interface used internally by the implementation of the MultiBinaryLongMap to indicate that anBinaryLongMap.EntryVisitor
implementation is "safe" and does not retain any references to passed Entries.static interface
MultiBinaryLongMap.SafePredicate
SafePredicate is a marker interface used internally by the implementation of the MultiBinaryLongMap to indicate that aPredicate
implementation is "safe" and does not retain any references to passed Entries.static class
MultiBinaryLongMap.WrapperBinaryLongMap
The WrapperBinaryLongMap is a BinaryLongMap implementation that wraps an underlying BinaryLongMap.
-
Field Summary
Fields Modifier and Type Field Description protected MultiBinaryLongMap.PrimaryBinaryLongMap
f_blmPrimary
The primary BinaryLongMap instance.protected MultiBinaryLongMap.LeftoverLongMapHolder
f_holderLeftover
The MaskedLongMapHolder representing the "leftover" space in the primary BinaryLongMap.protected ArrayList
f_listDelegates
The list of delegates (either a DelegateBLM, or a MaskedLongMapHolder) indexed by the freeprotected ReentrantReadWriteLock
f_rwLockMaster
The read/write lock for concurrency control for the BinaryRadixTree.protected MultiBinaryLongMap.LongStorage
f_storage
The underlying storage for the values.protected BinaryRadixTree
f_tree
The underlying storage for the keys and handles.
-
Constructor Summary
Constructors Constructor Description MultiBinaryLongMap()
Construct a MultiBinaryLongMap.MultiBinaryLongMap(ReentrantReadWriteLock lock)
Construct a MultiBinaryLongMap.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addListener(MultiBinaryLongMap.BinaryLongMapListener listener)
Add the specified listener to listen to changes that occur to the MultiBinaryLongMap's primary BinaryLongMap.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.BinaryLongMap
createBinaryLongMap()
Create a new BinaryLongMap that can be used to manage values for the set of keys present in the primary BinaryLongMap instance.protected MultiBinaryLongMap.DelegatingBinaryLongMap
createBinaryLongMapInternal()
Helper method to create a new delegating BinaryLongMap.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.protected static int
decodeRemainder(long l)
Extract the "remainder" portion (the portion not encoding theslot
) from the specified long that was stored in a BinaryLongMap.protected static int
decodeSlot(long l)
Extract a slot index from a long that was stored in a BinaryLongMap.protected static long
encodeRemainder(long l, int iRemainder)
Encode a 32-bit "remainder" value as a long that can be stored in a BinaryLongMap.protected static long
encodeSlot(long l, int iSlot)
Encode a slot index as a long that can be stored in a BinaryLongMap.protected static MultiBinaryLongMap.SafePredicate
ensureSafePredicate(Predicate<BinaryLongMap.Entry> predicate)
Return a SafePredicate based on the specified predicate implementation.protected static MultiBinaryLongMap.SafeEntryVisitor
ensureSafeVisitor(BinaryLongMap blm, BinaryLongMap.EntryVisitor visitor)
Return a SafeEntryVisitor based on the specified visitor implementation.MultiBinaryLongMap.PrimaryBinaryLongMap
getPrimaryBinaryLongMap()
Obtain a reference to the primary BinaryLongMap instance.void
releaseMap(BinaryLongMap blm)
Release one of the maps previously returned from eithercreateBinaryLongMap()
,createBinaryIntMap()
orcreateBitMap(int)
.protected void
releaseMapInternal(BinaryLongMap blm)
Helper method for releasing a BinaryLongMap created by this MultiBinaryLongMap.void
removeListener(MultiBinaryLongMap.BinaryLongMapListener listener)
Remove the specified listener from listening to changes that occur to the MultiBinaryLongMap's primary BinaryLongMap.
-
-
-
Field Detail
-
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 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 eithercreateBinaryLongMap()
,createBinaryIntMap()
orcreateBitMap(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 theslot
) 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 BinaryLongMapiSlot
- 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 BinaryLongMapiRemainder
- 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
-
-