org.neo4j.collection.primitive.hopscotch

Interface Table<VALUE>

All Superinterfaces:

AutoCloseable

All Known Implementing Classes:

IntArrayBasedKeyTable, IntKeyLongValueTable, IntKeyObjectValueTable, IntKeyTable, IntKeyUnsafeTable, LongKeyIntValueTable, LongKeyLongValueUnsafeTable, LongKeyObjectValueTable, LongKeyTable, LongKeyUnsafeTable, PowerOfTwoQuantizedTable, UnsafeTable

public interface Table<VALUE>
extends AutoCloseable

Table for storing and retrieving all entries managed by the HopScotchHashingAlgorithm. A table is responsible for storing and retrieving:

1. keys: a primitive long key
2. hop bits: a concept used by the hop-scotch algorithm to manage hash conflicts, a.k.a. neighbor
3. values: (OPTIONAL) value associated with each key. Optional in a setting where only the key is important, e.g. a set

The HopScotchHashingAlgorithm contains all hashing logic and a Table is a dump, straight forward data keeper. Optimizations for special keys or key/value combinations can be captured in implementations of this. The only restriction is that keys must be decimal type numbers, f.ex. short, int or long. Where the key "carrier" between the algorithm and the table is always going to be long since it can carry all the others. versioning is added to the table interface, but implementations can disable versioning by always returning the same and constant number in both version() and version(int). Versioning helps iterating over a constant set of entries at the same time as modifying the table.

Method Summary

Modifier and Type	Method and Description
int	capacity()
void	clear() Removes all entries from this table.
void	close() Free any resources
Table<VALUE>	grow() Grows the table to double that of the current size.
int	h()
long	hopBits(int index) A short summary of the hop bits format: It's a bit map represented as an int, where each set bit represents an offset where there's a neighbor for this index.
boolean	isEmpty()
long	key(int index)
int	mask()
long	move(int fromIndex, int toIndex) Moves the key/value from one index to another, any hop bits stay.
void	moveHopBit(int index, int hd, int delta) Moves one hop bit delta steps.
long	nullKey()
void	put(int index, long key, VALUE value) Puts (key/value) at the given index.
void	putHopBit(int index, int hd) Adds one hop bit to the set of hop bits at the given index.
VALUE	putValue(int index, VALUE value) Puts, actually overwrites, the value at the given index.
VALUE	remove(int index) Removes the currently assigned key/value from the given index.
void	removeHopBit(int index, int hd) Removes one hop bit from the set of hop bits at the given index.
int	size()
VALUE	value(int index) OPTIONAL operation.
int	version()
int	version(int index)

Method Detail

h

int h()

Returns:

H as defined by the hop-scotch algorithm, i.e. how many entries can share the same table index, i.e. how many conflicts there can be at most for any given table index.

capacity

int capacity()

Returns:

number of entries this table can hold at most.

size

int size()

Returns:

number of entries this table holds at the moment.

mask

int mask()

Returns:

a bit mask for doing table length modulo, for example when incrementing or decrementing a table index, so that it wraps around the edges.

key

long key(int index)

Parameters:

index - the table index to get the key for.

Returns:

the key at the given index. If there's no assigned key here then nullKey() will be returned.

value

VALUE value(int index)

OPTIONAL operation. Returns null if unsupported.

Parameters:

index -

Returns:

the value at the given index. If there's no assigned key here then null will be returned.

put

void put(int index,
         long key,
         VALUE value)

Puts (key/value) at the given index. This index must contractually be free at the point where the algorithm calls this method.

Parameters:

index - the index to put this key/value in.

key - the key to put.

value - the value to put.

putValue

VALUE putValue(int index,
               VALUE value)

Puts, actually overwrites, the value at the given index. This index will contractually be occupied at the point where the algorithm calls this method. This new value replaces the existing value at this index.

Parameters:

index - the index to put this value in.

value - the value to put at this index.

Returns:

the existing value at this index, before this new value was put there.

move

long move(int fromIndex,
          int toIndex)

Moves the key/value from one index to another, any hop bits stay. This is equivalent to a remove at fromIndex followed by a put at toIndex. After this method has been called there will no longer be any key/value assigned at fromIndex.

Parameters:

fromIndex - the index to move the key/value from.

toIndex - the index to move the key/value to.

Returns:

the affected key.

remove

VALUE remove(int index)

Removes the currently assigned key/value from the given index.

Parameters:

index - the index to remove key/value from.

Returns:

the existing value at this index.

hopBits

long hopBits(int index)

A short summary of the hop bits format: It's a bit map represented as an int, where each set bit represents an offset where there's a neighbor for this index. Here is the two least significant bytes in an example bit map carrying hop bits:

 ....[0000,0001][0000,0100]
 

In the above example, if we assume the index carrying these hop bits is 5, then index 5 has two neighbors: index 8 and index 14. (the least significant bit represents an offset of 1). Maximum number of hop bits is controlled by h(). Interesting to note is that hop bits for an index and key/value are not really associated, where a key/value can be moved to a new location, but the hop bits stay behind. The location of Hop bits is tied to table index, whereas the location of key/value is tied to table index AND hop bits.

Parameters:

index - the index to get the hop bits for.

Returns:

the hop bits for the given index.

putHopBit

void putHopBit(int index,
               int hd)

Adds one hop bit to the set of hop bits at the given index.

Parameters:

index - the index to add the hop bit at.

hd - h-delta, i.e. which hop bit to set, zero-based.

See Also:

hopBits(int)

moveHopBit

void moveHopBit(int index,
                int hd,
                int delta)

Moves one hop bit delta steps. If delta is positive it will be moved towards msb, if negative towards lsb.

Parameters:

index - the index to move the hop bit for.

hd - the hop bit to move.

delta - how far (and based on sign) which direction to move it in.

removeHopBit

void removeHopBit(int index,
                  int hd)

Removes one hop bit from the set of hop bits at the given index.

Parameters:

index - the index to remove the hop bit from.

hd - h-delta, i.e. which hop bit to remove, zero-based.

See Also:

hopBits(int)

nullKey

long nullKey()

Returns:

key representing an index that has not been assigned. Why is this a method? Since an implementation could based this value on h() for example, which although is final per table instance, changes from table to table.

grow

Table<VALUE> grow()

Grows the table to double that of the current size. This method should not populate the table, it's just responsible for growing the structure holding the entries. All entries should have nullKey() after this method has been called. The size() should be reset here as well since after it has grown then it will be re-populated immediately with the existing data.

Returns:

the new table.

isEmpty

boolean isEmpty()

Returns:

true if there are no entries in this table, otherwise false.

clear

void clear()

Removes all entries from this table.

version

int version()

Returns:

the version of the table, i.e. the version of the newest entry in the table.

version

int version(int index)

Parameters:

index - the index of the entry to get.

Returns:

the version of the entry by the given index in this table.

close

void close()

Free any resources

Specified by:

close in interface AutoCloseable