Skip navigation links

com.tangosol.util
Class MultiBinaryLongMap

java.lang.Object
com.tangosol.util.MultiBinaryLongMap

public class MultiBinaryLongMap

extends java.lang.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

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 a Lock 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 produce MultiBinaryLongMap.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 immutable BinaryLongMap.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 an BinaryLongMap.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 a Predicate 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

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 java.util.ArrayList	f_listDelegates The list of delegates (either a DelegateBLM, or a MaskedLongMapHolder) indexed by the free
protected java.util.concurrent.locks.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

MultiBinaryLongMap()
Construct a MultiBinaryLongMap.

MultiBinaryLongMap(java.util.concurrent.locks.ReentrantReadWriteLock lock)
Construct a MultiBinaryLongMap.

Method Summary

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 the slot) 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(com.oracle.common.base.Predicate 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 either createBinaryLongMap(), createBinaryIntMap() or createBitMap(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 java.util.concurrent.locks.ReentrantReadWriteLock f_rwLockMaster

The read/write lock for concurrency control for the BinaryRadixTree.

f_listDelegates

protected final java.util.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(java.util.concurrent.locks.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

ensureSafePredicate

protected static MultiBinaryLongMap.SafePredicate ensureSafePredicate(com.oracle.common.base.Predicate 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

Skip navigation links