org.infinispan.distribution.ch

Interface ConsistentHash

public interface ConsistentHash

A consistent hash algorithm implementation. Implementations would typically be constructed via a ConsistentHashFactory. A consistent hash assigns each key a list of owners; the number of owners is defined at creation time, but the consistent hash is free to return a smaller or a larger number of owners, depending on circumstances, as long as each key has at least one owner. The first element in the list of owners is the "primary owner". A key will always have a primary owner. The other owners are called "backup owners". This interface gives access to some implementation details of the consistent hash. Our consistent hashes work by splitting the hash space (the set of possible hash codes) into fixed segments and then assigning those segments to nodes dynamically. The number of segments is defined at creation time, and the mapping of keys to segments never changes. The mapping of segments to nodes can change as the membership of the cache changes. Normally application code doesn't need to know about this implementation detail, but some applications may benefit from the knowledge that all the keys that map to one segment are always located on the same server.

Since:

4.0

Author:

Manik Surtani, Mircea.Markus@jboss.com, Dan Berindei, anistor@redhat.com

See Also:

Non-BlockingStateTransferV2

Method Summary

Methods

Modifier and Type	Method and Description
Hash	getHashFunction()
List	getMembers() Should return the addresses of the nodes used to create this consistent hash.
int	getNumOwners()
int	getNumSegments()
Set	getPrimarySegmentsForOwner(Address owner) Returns the segments that this cache member is the primary owner for.
String	getRoutingTableAsString() Returns a string containing all the segments and their associated addresses.
int	getSegment(Object key)
Set	getSegmentsForOwner(Address owner) Returns the segments owned by a cache member.
boolean	isKeyLocalToNode(Address nodeAddress, Object key) Test to see whether a key is owned by a given node.
Set	locateAllOwners(Collection keys) The logical equivalent of calling ConsistentHash.locateOwners(java.lang.Object) multiple times for each key in the collection of keys and merging the results.
List	locateOwners(Object key) Finds all the owners of a key.
List	locateOwnersForSegment(int segmentId)
Address	locatePrimaryOwner(Object key) Should be equivalent to return the first element of ConsistentHash.locateOwners(java.lang.Object).
Address	locatePrimaryOwnerForSegment(int segmentId)

Method Detail

getNumOwners

int getNumOwners()

Returns:

The configured number of owners for each key. Note that {code @getOwners(key)} may return a different number of owners.

getHashFunction

Hash getHashFunction()

getNumSegments

int getNumSegments()

Returns:

The actual number of hash space segments. Note that it may not be the same as the number of segments passed in at creation time.

getMembers

List getMembers()

Should return the addresses of the nodes used to create this consistent hash.

Returns:

set of node addresses.

locatePrimaryOwner

Address locatePrimaryOwner(Object key)

Should be equivalent to return the first element of ConsistentHash.locateOwners(java.lang.Object). Useful as a performance optimization, as this is a frequently needed information.

Parameters:

key - key to locate

Returns:

the address of the owner

locateOwners

List locateOwners(Object key)

Finds all the owners of a key. The first element in the returned list is the primary owner.

Parameters:

key - key to locate

Returns:

An unmodifiable list of addresses where the key resides. Will never be null, and it will always have at least 1 element.

locateAllOwners

Set locateAllOwners(Collection keys)

The logical equivalent of calling ConsistentHash.locateOwners(java.lang.Object) multiple times for each key in the collection of keys and merging the results. Implementations may be optimised for such a bulk lookup.

Parameters:

keys - keys to locate.

Returns:

set of nodes that own at least one of the keys.

isKeyLocalToNode

boolean isKeyLocalToNode(Address nodeAddress,
                       Object key)

Test to see whether a key is owned by a given node.

Parameters:

nodeAddress - address of the node to test

key - key to test

Returns:

true if the key is mapped to the address; false otherwise

getSegment

int getSegment(Object key)

Returns:

The hash space segment that a key maps to.

locateOwnersForSegment

List locateOwnersForSegment(int segmentId)

Returns:

All the nodes that own a given hash space segment, first address is the primary owner. The returned list is unmodifiable.

locatePrimaryOwnerForSegment

Address locatePrimaryOwnerForSegment(int segmentId)

Returns:

The primary owner of a given hash space segment. This is equivalent to locateOwnersForSegment(segmentId).get(0) but is more efficient

getSegmentsForOwner

Set getSegmentsForOwner(Address owner)

Returns the segments owned by a cache member.

Parameters:

owner - the address of the member

Returns:

a non-null set of segment IDs

getPrimarySegmentsForOwner

Set getPrimarySegmentsForOwner(Address owner)

Returns the segments that this cache member is the primary owner for.

Parameters:

owner - the address of the member

Returns:

a non-null set of segment IDs

getRoutingTableAsString

String getRoutingTableAsString()

Returns a string containing all the segments and their associated addresses.