hashring

Documentation

Index

• Variables
• type CacheNode
• type HashRing
  • func HashRingInit(opts ...HashRingConfigFn) *HashRing
  • func (ring *HashRing) AddNode(node CacheNode) error
  • func (ring *HashRing) GetNode(key string) (CacheNode, error)
  • func (ring *HashRing) RemoveNode(node CacheNode) error
• type HashRingConfigFn
  • func EnableVerboseLogs(enabled bool) HashRingConfigFn
  • func SetHashFunction(f func() hash.Hash64) HashRingConfigFn

Variables

var (
	ErrNoConnectedNodes = errors.New("No connected Nodes available")
	ErrNodeExits        = errors.New("Node already exists")
	ErrNodeNotFound     = errors.New("Node not found")
	ErrInHashingKey     = errors.New("Error in Hashing Key")
)

Global error variables which has all error types to return

Types

type CacheNode

type CacheNode interface {
	GetIdentifier() string
}

GetIdentifier gives each CacheNode its own identity

type HashRing

type HashRing struct {
	// contains filtered or unexported fields
}

HashRing represents a consistent hash ring data structure that maps keys to nodes in a distributed system. It maintains a sorted list of node hash values and uses binary search to efficiently find the appropriate node for any given key. The ring supports dynamic addition and removal of nodes while maintaining consistent key-to-node mapping. Fields:

• mu: Read-write mutex for thread-safe concurrent access to the hash ring
• config: Configuration settings including hash function and logging preferences
• nodes: Thread-safe map storing nodes keyed by their hash values
• sortedKeyOfNodes: Sorted slice of node hash values used for efficient binary search lookups

func HashRingInit

func HashRingInit(opts ...HashRingConfigFn) *HashRing

HashRingInit creates and initializes a new HashRing instance with optional configuration. It accepts variadic HashRingConfigFn options to customize the hash ring behavior such as setting a custom hash function or enabling verbose logs. By default, it uses fnv.New64a as the hash function and disables logging. Returns a pointer to the initialized HashRing ready for adding nodes and performing key-to-node lookups.

func (*HashRing) AddNode

func (ring *HashRing) AddNode(node CacheNode) error

AddNode adds a new node to the HashRing. It computes the hash value of the node's identifier and stores the node at that hash position. The node's hash is also added to the sortedKeyOfNodes slice which is then sorted to maintain the ring structure. If a node with the same hash already exists, it returns ErrNodeExits. This method is thread-safe and can be used to dynamically add nodes to the hash ring (for example, adding a new database shard to a distributed system).

func (*HashRing) GetNode

func (ring *HashRing) GetNode(key string) (CacheNode, error)

GetNode retrieves the appropriate node from the HashRing for a given key. It computes the hash value of the key and uses binary search on the sorted node hashes to find the first node whose hash is greater than or equal to the key's hash. If no such node exists, it wraps around to the first node in the ring (consistent hashing behavior). This method is useful for determining which node should handle a particular key (for example, finding which database shard to query for a given data key). Returns the node and nil error on success, or nil and an error if no nodes are available or if the key cannot be hashed.

func (*HashRing) RemoveNode

func (ring *HashRing) RemoveNode(node CacheNode) error

RemoveNode removes an existing node from the HashRing. It computes the hash value of the node's identifier, removes the node from the nodes map, and removes its hash from the sortedKeyOfNodes slice. If the node does not exist, it returns ErrNodeNotFound. This method is thread-safe and can be used to dynamically remove nodes from the hash ring (for example, removing a database shard that is being decommissioned from a distributed system).

type HashRingConfigFn

type HashRingConfigFn func(*hashRingConfig)

HashRingConfigFn is a function type that modifies the hashRingConfig. It is used as an option pattern to configure HashRing during initialization. Functions like SetHashFunction and EnableVerboseLogs return HashRingConfigFn which can be passed to HashRingInit to customize the hash ring behavior.

func EnableVerboseLogs

func EnableVerboseLogs(enabled bool) HashRingConfigFn

EnableVerboseLogs returns a HashRingConfigFn that enables or disables verbose logging for HashRing operations. When enabled, the HashRing will log operations like adding nodes, removing nodes, and key-to-node mappings. This is useful for debugging and monitoring the hash ring behavior.

func SetHashFunction

func SetHashFunction(f func() hash.Hash64) HashRingConfigFn

SetHashFunction returns a HashRingConfigFn that sets a custom hash function for the HashRing. By default, HashRing uses fnv.New64a, but you can provide your own hash function implementation. This is useful when you need a different hashing algorithm or want to customize the hash distribution.