Package com.qfs.dic.impl

Class AChristmasDictionary<K>

java.lang.Object

com.qfs.dic.impl.AChristmasDictionary<K>

Type Parameters:

K - The type of Objects stored in this dictionary

All Implemented Interfaces:

IConcurrentDictionary<K>, IDictionary<K>, IWritableDictionary<K>, ICompressible, IMemoryMonitored, Externalizable, Serializable

Direct Known Subclasses:

ChristmasDictionary, ChristmasDictionaryDouble, ChristmasDictionaryFloat, ChristmasDictionaryInteger, ChristmasDictionaryLong

public abstract class AChristmasDictionary<K>
extends Object
implements IConcurrentDictionary<K>, Externalizable

An IConcurrentDictionary where most of the regular operations are non-blocking.

The main exceptions to this rule are:

• the operations happening concurrently with a resize of the dictionary
• a read or write operation on a given key happening concurrently with another write operation whose key's hash value is the same as the first key's hash value.

Its name comes from the fact that it has been designed on Christmas eve.

Author:

ActiveViam

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from interface com.qfs.dic.IConcurrentDictionary

IConcurrentDictionary.IDictionaryAction<K>

Nested classes/interfaces inherited from interface com.qfs.dic.IWritableDictionary

IWritableDictionary.IDoubleDictionary, IWritableDictionary.IFloatDictionary, IWritableDictionary.IIntegerDictionary, IWritableDictionary.ILongDictionary

Field Summary

Fields inherited from interface com.qfs.dic.IConcurrentDictionary

NEW_MAPPING

Fields inherited from interface com.qfs.dic.IDictionary

DEFAULT_INITIAL_CAPACITY, ID_GENERATOR

Method Summary

Modifier and Type	Method	Description
void	clear()	Clears the whole content of the dictionary.
ATasksPerNumaNode	compress(boolean destroyOnly)	Collects all the useless objects stored off-heap and free that memory space without changing logical content of existing versions.
void	destroy()	Frees all resources held by this data structure.
long	getDictionaryId()	Gets the unique ID of this dictionary useful for monitoring).
int	getDoublePosition(double key)	Searches for a double in the dictionary.
int	getFloatPosition(float key)	Searches for a float in the dictionary.
int	getIntPosition(int key)	Searches for an integer in the dictionary.
int	getLongPosition(long key)	Searches for a long in the dictionary.
IMemoryStatistic	getMemoryStatistic()	Gets the IMemoryStatistic of the component being monitored.
K	getNullValue()	Gets the value representing a "null" for a dictionarized value.
int	getOrder()	Returns the order of the dictionary.
int	getPosition(K key)	Searches for a key in the dictionary.
boolean	isNullable()	Returns whether this dictionary is nullable (it is capable to map the null key).
int	map(K key)	Indexes a new object in the dictionary.
long	map(K key, IConcurrentDictionary.IDictionaryAction<K> mappingAction, IConcurrentDictionary.IDictionaryAction<K> existingKeyAction)	Maps a new object in the dictionary the same way as IWritableDictionary.map(Object).
int	mapDouble(double key)	Indexes a double as a new key in the dictionary.
int	mapFloat(float key)	Indexes a float as a new key in the dictionary.
int	mapInt(int key)	Indexes an integer as a new key in the dictionary.
int	mapLong(long key)	Indexes a long as a new key in the dictionary.
K	read(int position)	Reads the object stored at a given dictionary position.
double	readDouble(int position)	Reads the double stored at a given dictionary position.
void	readExternal(ObjectInput in, K nullValue)	Reads the size() and keys in order and rebuilds the inner dictionary.
float	readFloat(int position)	Reads the float stored at a given dictionary position.
int	readInt(int position)	Reads the integer stored at a given dictionary position.
long	readLong(int position)	Reads the long stored at a given dictionary position.
static int	regularizeHash(int h)	Regularizes the given hash value so that it can be efficiently used in this dictionary.
int	size()	Gets the size (number of entries) of this dictionary.
String	toString()
void	writeExternal(ObjectOutput out)	Simply writes the size() and keys in order using InnerChristmasDictionary.writeSerializedKeys(ObjectOutput).

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.io.Externalizable

readExternal

Methods inherited from interface com.qfs.memory.ICompressible

compress

Methods inherited from interface com.qfs.dic.IConcurrentDictionary

supportConcurrentReads, supportConcurrentWrites

Methods inherited from interface com.qfs.dic.IDictionary

copyInto, getFirstElements, getSize, getType

Methods inherited from interface com.qfs.dic.IWritableDictionary

mapFromCell

Method Detail

getNullValue

public K getNullValue()

Gets the value representing a "null" for a dictionarized value.

Returns:

the chosen value for null

size

public int size()

Description copied from interface: IDictionary

Gets the size (number of entries) of this dictionary.

Specified by:

size in interface IDictionary<K>

Returns:

the size

clear

public void clear()

Description copied from interface: IWritableDictionary

Clears the whole content of the dictionary.

This operation will not recreate or resize the internal data structures of the dictionary, but erase them.

Specified by:

clear in interface IWritableDictionary<K>

isNullable

public boolean isNullable()

Description copied from interface: IDictionary

Returns whether this dictionary is nullable (it is capable to map the null key).

Trying to map or search the null element on a dictionary that is non-nullable will at some point throw a NullPointerException.

Specified by:

isNullable in interface IDictionary<K>

Returns:

true if this dictionary is nullable, false otherwise

destroy

public void destroy()

Description copied from interface: IWritableDictionary

Frees all resources held by this data structure.

Specified by:

destroy in interface IWritableDictionary<K>

compress

public ATasksPerNumaNode compress(boolean destroyOnly)

Description copied from interface: ICompressible

Collects all the useless objects stored off-heap and free that memory space without changing logical content of existing versions.

Basically, this method tries to remove all the chunks without valid rows or converts all chunks into sparse chunks whether or not the ratio of valid rows and total rows reaches its critical value.

Specified by:

compress in interface ICompressible

Parameters:

destroyOnly - if true, the compression actions should only try to destroy useless chunks, and not to compress the sparse ones, this is to avoid asking for more (transient) direct memory

Returns:

all the actions to run to compress this component, mapped by thread pool ID

readExternal

public void readExternal(ObjectInput in,
                         K nullValue)
                  throws IOException,
                         ClassNotFoundException

Reads the size() and keys in order and rebuilds the inner dictionary.

Parameters:

in - The input stream

nullValue - The value representing a null value for a value.

Throws:

IOException - if it fails to read the input

ClassNotFoundException - if one of the serialized data class does not exist

writeExternal

public void writeExternal(ObjectOutput out)
                   throws IOException

Simply writes the size() and keys in order using InnerChristmasDictionary.writeSerializedKeys(ObjectOutput).

Specified by:

writeExternal in interface Externalizable

Parameters:

out - The output stream

Throws:

IOException

regularizeHash

public static final int regularizeHash(int h)

Regularizes the given hash value so that it can be efficiently used in this dictionary.

Parameters:

h - The hash value to regularize

Returns:

The regularized hash value.

map

public long map(K key,
                IConcurrentDictionary.IDictionaryAction<K> mappingAction,
                IConcurrentDictionary.IDictionaryAction<K> existingKeyAction)

Description copied from interface: IConcurrentDictionary

Maps a new object in the dictionary the same way as IWritableDictionary.map(Object).

If a new mapping is created because of this call (i.e. the key did not already exist in the dictionary), the associated mapping function is invoked before the mapping is made visible to the other threads. It will only become visible after the callback has returned.
Other calls to IWritableDictionary.map(Object) should block until this new mapping is made visible and return the newly mapped position afterwards. Other calls to IDictionary.getPosition(K) might either block or return -1 if the new mapping is not visible yet.

If a mapping already existed for this key, the existing key action is invoked before returning.

The returned value is a long whose lower 4 bytes represent the mapped object's position, while its upper 4 bytes are used for various flags. The returned value can therefore simply be casted as an int to get the key's address.

Specified by:

map in interface IConcurrentDictionary<K>

Parameters:

key - the object to map in this dictionary

mappingAction - the action to execute if a new mapping is created for this object, can be null

existingKeyAction - the action to execute if a mapping already existed for this key, can be null

Returns:

a long that packs the key's dictionary address in its lower 4 bytes and various flags in the remaining upper 4 bytes

map

public int map(K key)

Description copied from interface: IWritableDictionary

Indexes a new object in the dictionary.

If the object already existed in the dictionary (with respect to the equals / hashCode contract) the previous copy of the object is left in the dictionary. The new object copy can then be safely reused or cleared without any impact to the dictionary consistency.

Specified by:

map in interface IWritableDictionary<K>

Parameters:

key - the object

Returns:

the address of the object in the dictionary buffer

mapDouble

public int mapDouble(double key)

Description copied from interface: IWritableDictionary

Indexes a double as a new key in the dictionary.

If the key already existed in the dictionary (with respect to the equals / hashCode contract) the previous copy of the object is left in the dictionary. The new object copy can then be safely reused or cleared without any impact to the dictionary consistency.

This will throw UnsupportedOperationException if the type Double is not compatible with the type of the dictionary.

Specified by:

mapDouble in interface IWritableDictionary<K>

Parameters:

key - the double to map

Returns:

the address of the object in the dictionary buffer

mapFloat

public int mapFloat(float key)

Description copied from interface: IWritableDictionary

Indexes a float as a new key in the dictionary.

If the key already existed in the dictionary (with respect to the equals / hashCode contract) the previous copy of the object is left in the dictionary. The new object copy can then be safely reused or cleared without any impact to the dictionary consistency.

This will throw UnsupportedOperationException if the type Float is not compatible with the type of the dictionary.

Specified by:

mapFloat in interface IWritableDictionary<K>

Parameters:

key - the float to map

Returns:

the address of the object in the dictionary buffer

mapInt

public int mapInt(int key)

Description copied from interface: IWritableDictionary

Indexes an integer as a new key in the dictionary.

If the key already existed in the dictionary (with respect to the equals / hashCode contract) the previous copy of the object is left in the dictionary. The new object copy can then be safely reused or cleared without any impact to the dictionary consistency.

This will throw UnsupportedOperationException if the type Integer is not compatible with the type of the dictionary.

Specified by:

mapInt in interface IWritableDictionary<K>

Parameters:

key - the integer to map

Returns:

the address of the object in the dictionary buffer

mapLong

public int mapLong(long key)

Description copied from interface: IWritableDictionary

Indexes a long as a new key in the dictionary.

If the key already existed in the dictionary (with respect to the equals / hashCode contract) the previous copy of the object is left in the dictionary. The new object copy can then be safely reused or cleared without any impact to the dictionary consistency.

This will throw UnsupportedOperationException if the type Long is not compatible with the type of the dictionary.

Specified by:

mapLong in interface IWritableDictionary<K>

Parameters:

key - the long to map

Returns:

the address of the object in the dictionary buffer

read

public K read(int position)

Description copied from interface: IDictionary

Reads the object stored at a given dictionary position.

Specified by:

read in interface IDictionary<K>

Parameters:

position - the position in the dictionary where to read the object

Returns:

the Object at the given position

readDouble

public double readDouble(int position)

Description copied from interface: IDictionary

Reads the double stored at a given dictionary position.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Double.

Specified by:

readDouble in interface IDictionary<K>

Parameters:

position - the position in the dictionary

Returns:

the double stored at the given position

readFloat

public float readFloat(int position)

Description copied from interface: IDictionary

Reads the float stored at a given dictionary position.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Float.

Specified by:

readFloat in interface IDictionary<K>

Parameters:

position - the position in the dictionary

Returns:

the float stored at the given position

readInt

public int readInt(int position)

Description copied from interface: IDictionary

Reads the integer stored at a given dictionary position.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Int.

Specified by:

readInt in interface IDictionary<K>

Parameters:

position - the position in the dictionary

Returns:

the integer stored at the given position

readLong

public long readLong(int position)

Description copied from interface: IDictionary

Reads the long stored at a given dictionary position.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Long.

Specified by:

readLong in interface IDictionary<K>

Parameters:

position - the position in the dictionary

Returns:

the long stored at the given position

getPosition

public int getPosition(K key)

Description copied from interface: IDictionary

Searches for a key in the dictionary.

Specified by:

getPosition in interface IDictionary<K>

Parameters:

key - the object we are looking for

Returns:

position of the key in the dictionary, or -1 if the key is not in the dictionary

getDoublePosition

public int getDoublePosition(double key)

Description copied from interface: IDictionary

Searches for a double in the dictionary.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Double.

Specified by:

getDoublePosition in interface IDictionary<K>

Parameters:

key - the double

Returns:

position of the key in the dictionary, or -1 if the key is not in the dictionary

getFloatPosition

public int getFloatPosition(float key)

Description copied from interface: IDictionary

Searches for a float in the dictionary.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Float.

Specified by:

getFloatPosition in interface IDictionary<K>

Parameters:

key - the float

Returns:

position of the key in the dictionary, or -1 if the key is not in the dictionary

getIntPosition

public int getIntPosition(int key)

Description copied from interface: IDictionary

Searches for an integer in the dictionary.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Int.

Specified by:

getIntPosition in interface IDictionary<K>

Parameters:

key - the integer

Returns:

position of the key in the dictionary, or -1 if the key is not in the dictionary

getLongPosition

public int getLongPosition(long key)

Description copied from interface: IDictionary

Searches for a long in the dictionary.

Will throw UnsupportedOperationException if the stored object in the dictionary is not of type Long.

Specified by:

getLongPosition in interface IDictionary<K>

Parameters:

key - the long

Returns:

position of the key in the dictionary, or -1 if the key is not in the dictionary

getMemoryStatistic

public IMemoryStatistic getMemoryStatistic()

Description copied from interface: IMemoryMonitored

Gets the IMemoryStatistic of the component being monitored.

Specified by:

getMemoryStatistic in interface IMemoryMonitored

Returns:

the IMemoryStatistic

getOrder

public int getOrder()

Returns the order of the dictionary.

Specified by:

getOrder in interface IDictionary<K>

Returns:

the order

getDictionaryId

public long getDictionaryId()

Description copied from interface: IDictionary

Gets the unique ID of this dictionary useful for monitoring).

Specified by:

getDictionaryId in interface IDictionary<K>

Returns:

the ID of this dictionary (unique amongst all dictionaries used in the application)

toString

public String toString()

Overrides:

toString in class Object