Partition Hashing

​

The Hasher interface

type Hasher interface {
    // HashCode is responsible for generating unsigned, 64-bit hash of provided byte slice
    HashCode(key []byte) uint64
}

​

Cluster mode

1. Key to partition. Every registry key (actor name, grain identity, job ID) is hashed, and the hash code modulo the partition count selects the partition that stores the record: partition = HashCode(key) % partitionCount.
2. Partition to node. Partitions are assigned to cluster members through a consistent-hash ring built with the same hasher: each partition ID is itself hashed to position it on the ring. When nodes join or leave, only the affected partitions move.

​

Correlation with WithPartitionCount

clusterConfig := actor.NewClusterConfig().
    WithDiscovery(provider).
    WithKinds(new(AccountActor)).
    WithPartitionCount(521) // a prime number

• Use a prime count. Modulo folds the hash’s 64 bits into partitionCount buckets. A prime count avoids resonance between patterned hash outputs and the modulo, which matters even more when you substitute a weaker custom hasher for xxh3. The default 271 is prime; keep that property when changing it.
• The count sets the rebalancing granularity. A partition is the unit of ownership and relocation: with more partitions, load spreads more evenly across members and topology changes move smaller chunks. Pick a count comfortably above the maximum number of nodes you expect, otherwise some nodes own several partitions while others sit idle.
• The count multiplies memory overhead. Each partition holding data allocates its own storage table (ClusterConfig.WithTableSize, default 4 MB), so worst-case registry memory grows with partitionCount x tableSize. Very large counts buy smoother balancing at the price of baseline memory.
• Same consistency rule as the hasher. All nodes must use the same partition count. Because the mapping is hash % count, changing the count remaps almost every key to a different partition, exactly like changing the hash function.

​

Benefits

• Deterministic, coordination-free lookups. Resolving an actor by name (ActorOf, SpawnOn, grain activation) requires no directory service and no broadcast: the owner is a pure function of the key.
• Even data and load distribution. A well-distributed hash spreads registry records, and therefore lookup and write traffic, uniformly across partitions and nodes.
• Bounded reshuffling. Consistent hashing over partitions means a topology change relocates only the partitions owned by the affected node instead of rehashing the whole keyspace.

​

Setting a custom hasher

clusterConfig := actor.NewClusterConfig().
    WithDiscovery(provider).
    WithKinds(new(AccountActor)).
    WithPartitionCount(521).
    WithPartitionHasher(myHasher{})

system, err := actor.NewActorSystem("accounts",
    actor.WithLogger(logger),
    actor.WithRemote(remote.NewConfig("0.0.0.0", 8080)),
    actor.WithCluster(clusterConfig),
)

• Deterministic and stable. The same byte slice must produce the same hash code on every node, across process restarts, Go versions, and CPU architectures. Never use a per-process random seed (for example hash/maphash with a random seed).
• Identical cluster-wide. Every node must be configured with the same hasher. Nodes with different hashers disagree on partition ownership, and registry reads and writes silently miss each other.
• Uniform. A skewed hash concentrates keys in a few partitions and turns the nodes owning them into hot spots.
• Fast. The hasher runs on every registry read and write; prefer allocation-free implementations.

​

Non-cluster (standalone) mode

• Sticky, per-key processing. All messages for one entity (an order, a session, a device) are handled by one routee, preserving per-key ordering.
• Cache locality. A routee accumulates state for the keys it owns instead of every routee holding everything.