API Reference¶
HashRing ¶
A consistent hash ring backed by a Rust implementation.
Nodes are added with optional weights, and keys are deterministically mapped to a node by hashing. Useful for distributing work, cache shards, or storage assignments across a changing pool of servers.
Supports len(ring) for the node count, name in ring for membership,
for name in ring for iteration, ring[key] for subscript lookup
(raises KeyError on an empty ring), and pickling for state transfer.
add_node
method descriptor
¶
Add a node to the ring.
Adding a node that is already present is a no-op. Increase weight
to give a node a proportionally larger share of the keyspace.
hostname, port, and instance are optional metadata fields that
can be retrieved later via get_node_hostname / get_node_port /
get_node_instance.
get_node
method descriptor
¶
Return the node responsible for key, or None if the ring is empty.
get_node_batch
method descriptor
¶
Batch variant of get_node. Releases the GIL during lookup.
Returns a list aligned with the input keys, where each entry is the
owning node name or None if the ring is empty.
get_node_hostname
method descriptor
¶
Return the hostname of the named node, or None if not set or unknown.
get_node_instance
method descriptor
¶
Return the instance object attached to the named node, or None.
The instance can be any Python object passed via add_node(instance=...).
get_node_port
method descriptor
¶
Return the port of the named node, or None if not set or unknown.
get_node_weight
method descriptor
¶
Return the weight of the named node, or None if it is not registered.
get_replicas
method descriptor
¶
Return up to count distinct nodes responsible for key.
The first element is the primary owner (same as get_node); the rest
are walked clockwise around the ring. Useful for replication where the
same key must be stored on multiple nodes.
nodes
property
¶
Mapping of node name to its metadata.
Each inner dict contains weight, vnodes, hostname, port,
and instance (the last three may be None if not set).
remove_node
method descriptor
¶
Remove a node from the ring. No-op if the node was not present.