Package org.infinispan.distribution.ch
Interface ConsistentHash
- All Known Implementing Classes:
AbstractConsistentHash
,DefaultConsistentHash
,ReplicatedConsistentHash
,ScatteredConsistentHash
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.
The first element in the list of owners is the "primary owner". The other owners are called "backup owners".
Some implementations guarantee that there will always be a primary owner, others do not.
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:
-
Method Summary
Modifier and TypeMethodDescriptionThe capacity factor of each member.Should return the addresses of the nodes used to create this consistent hash.int
Returns the segments that this cache member is the primary owner for.Returns a string containing all the segments and their associated addresses.getSegmentsForOwner
(Address owner) Returns the segments owned by a cache member.default boolean
default boolean
isSegmentLocalToNode
(Address nodeAddress, int segmentId) Check if a segment is local to a given member.locateOwnersForSegment
(int segmentId) locatePrimaryOwnerForSegment
(int segmentId) default ConsistentHash
remapAddresses
(UnaryOperator<Address> remapper) Returns a new ConsistentHash with the addresses remapped according to the providedUnaryOperator
.default ConsistentHash
remapAddressRemoveMissing
(UnaryOperator<Address> remapper) Same asremapAddresses(UnaryOperator)
but skip missing members.default void
Writes this ConsistentHash to the specified scoped state.
-
Method Details
-
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
Should return the addresses of the nodes used to create this consistent hash.- Returns:
- set of node addresses.
-
locateOwnersForSegment
- Returns:
- All the nodes that own a given hash space segment, first address is the primary owner. The returned list is unmodifiable.
-
locatePrimaryOwnerForSegment
- Returns:
- The primary owner of a given hash space segment. This is equivalent to
locateOwnersForSegment(segmentId).get(0)
but is more efficient
-
isSegmentLocalToNode
Check if a segment is local to a given member.Implementation note: normally key-based method are implemented based on segment-based methods. Here, however, we need a default implementation for the segment-based method for backwards-compatibility reasons.
- Since:
- 8.2
-
isReplicated
default boolean isReplicated()- Returns:
true
if every member owns every segment. This allows callers to skip computing the segment of a key in some cases.
-
getSegmentsForOwner
Returns the segments owned by a cache member.- Parameters:
owner
- the address of the member- Returns:
- a non-null set of segment IDs, may or may not be unmodifiable, which shouldn't be modified by caller.
The set is empty if
owner
is not a member of the consistent hash.
-
getPrimarySegmentsForOwner
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, may or may not be unmodifiable, which shouldn't be modified by caller.
The set is empty if
owner
is not a member of the consistent hash.
-
getRoutingTableAsString
String getRoutingTableAsString()Returns a string containing all the segments and their associated addresses. -
toScopedState
Writes this ConsistentHash to the specified scoped state. Before invoking this method, the ConsistentHash addresses will have to be replaced with their correspondingPersistentUUID
s- Parameters:
state
- the state to which this ConsistentHash will be written
-
remapAddresses
Returns a new ConsistentHash with the addresses remapped according to the providedUnaryOperator
. If an address cannot me remapped (i.e. the remapper returns null) this method should return null.- Parameters:
remapper
- the remapper which given an address replaces it with another one- Returns:
- the remapped ConsistentHash or null if one of the remapped addresses is null
-
remapAddressRemoveMissing
Same asremapAddresses(UnaryOperator)
but skip missing members.- Parameters:
remapper
- : the remapper which given an address replaces it with another one- Returns:
- the remapped ConsistentHash
-
getCapacityFactors
The capacity factor of each member. Determines the relative capacity of each node compared to the others. Ifnull
, all the members are assumed to have a capacity factor of 1.
-