Allocation strategy
このコンテンツはまだ日本語訳がありません。
The sharding coordinator picks a node for each shard:
- At first contact — when a shard ID appears for the first
time, the coordinator runs
allocate(shardId, candidates, currentShards)to pick its owner. - On rebalance — every few seconds, the coordinator runs
rebalance(currentShards, candidates, inProgress)to find shards that should move.
The two built-in strategies trade simplicity for balance:
| Strategy | Allocation | Rebalance |
|---|---|---|
HashAllocationStrategy (default) | shardId mod sorted-candidates | Only when the set of candidates that are up changes, once that change has settled — but then most shards at once. |
LeastShardAllocationStrategy | Candidate with fewest shards. | Drains the busiest node into the rest. |
HashAllocationStrategy
Section titled “HashAllocationStrategy”import { HashAllocationStrategy, StartShardingOptions } from 'actor-ts/cluster';
const startShardingOptions = StartShardingOptions.create() .withTypeName('cart') .withEntityActor(CartActor) .withExtractEntityId((message) => message.entityId) .withAllocationStrategy(new HashAllocationStrategy());sharding.start( startShardingOptions, // default);The formula:
const sorted = [...candidates].sort();return sorted[shardId % sorted.length];Picks:
- Deterministic — given the same candidate set, same shards always land on same nodes.
- Minimal rebalance — only shards whose hash-target changes
need to move (when nodes join or leave). “Minimal” is relative to
doing it at all, not to how much moves: the modulus changes for
most shards when the candidate count does, so at
numShards = 64a 1 → 2 join re-homes 32 shards, a 2 → 3 join 42 to 44 and a 3 → 4 join 46 to 49. The range is address order at work: the candidates are sorted, so the figure depends on where the new node sorts — the low end when it sorts last, the high end when it sorts first. The strategy proposes all of them in one pass; what keeps that from arriving as one burst is the coordinator’s own ceiling — see the ceiling on churn. - Zero state — the strategy doesn’t track anything; it’s a pure function.
Doesn’t:
- Balance by load — uneven entity activity means some nodes end up busier than others, even with the same shard count.
- Compensate for slow nodes — a struggling member still gets its fair share of shards.
Right for uniform workloads where shards are roughly equal in cost, or as a sensible default while you measure whether you need something smarter.
LeastShardAllocationStrategy
Section titled “LeastShardAllocationStrategy”import { LeastShardAllocationStrategy, StartShardingOptions } from 'actor-ts/cluster';
const shardingOptions = StartShardingOptions.create() // ... .withAllocationStrategy(new LeastShardAllocationStrategy( /* rebalanceThreshold */ 1, /* maxSimultaneousRebalance */ 3, ));sharding.start(shardingOptions);The formula:
- Allocate: pick the candidate with the fewest shards currently hosted (ties broken by address order).
- Rebalance: first, every shard on a node that is no candidate —
a region refused over its shard count, or on a member without the
type’s role — whatever the candidates’ spread. Then, if
max(shardCount) - min(shardCount) >= rebalanceThresholdamong the candidates, move shards off the busiest node(s) to the least. At mostmaxSimultaneousRebalanceshards per pass, both kinds together.
Picks:
- Converges to balance even when nodes have joined / left unevenly.
- Throttled rebalance — bounded per-pass moves avoid thrashing.
- Address-tiebreak — deterministic ordering with no surprises.
Doesn’t:
- Know about per-shard load — it counts shards, not work. Two shards holding very different amounts of work look the same.
- React instantly —
maxSimultaneousRebalancecaps the per-pass movement; in a 100-shard cluster gaining a new node, full rebalance takes ~33 passes (×rebalanceInterval — typically a minute or so).
Tuning the knobs
Section titled “Tuning the knobs”new LeastShardAllocationStrategy( /* rebalanceThreshold */ 2, // trigger only when imbalance ≥ 2 /* maxSimultaneousRebalance */ 5, // up to 5 shards move per pass);rebalanceThreshold— bigger value = less churn, more tolerance for imbalance.1makes any imbalance trigger a rebalance;5waits for a real difference.maxSimultaneousRebalance— bigger value = faster convergence, more handoff traffic. 3 is a reasonable middle.
This cap and the configured
rebalance ceiling
are two different levels and both apply: maxSimultaneousRebalance
bounds what this strategy proposes per pass, the ceiling bounds
what the coordinator accepts from any strategy. A strategy that
caps itself is therefore not a substitute for the ceiling — the
default one caps nothing, and neither does one you write.
For 100-shard clusters with frequent membership churn, raise both (threshold ~3, max ~10). For 16-shard clusters where each shard move is expensive (large state), keep them low.
Custom strategies
Section titled “Custom strategies”Implement the interface:
interface AllocationStrategy { allocate( shardId: number, candidates: ReadonlyArray<NodeAddress>, currentShards: ReadonlyMap<string, ReadonlySet<number>>, ): NodeAddress;
rebalance( currentShards: ReadonlyMap<string, ReadonlySet<number>>, candidates: ReadonlyArray<NodeAddress>, rebalanceInProgress: ReadonlySet<number>, ): Set<number>;}The call protocol
Section titled “The call protocol”The coordinator never places a shard on a region whose member is not
up, and it tracks how long the set of regions whose member is up —
the eligible regions — has held still (see
members that are not up).
That decides how your strategy is called:
- While the set is settling,
allocatemay be asked twice for one shard: first with every registered region that could host the type and the shards every registered region holds — where the shard would go with everyone in view — and, only when it picks one whose member is not up, again with the eligible regions alone and their shards.rebalanceis not called at all. - Once the set has held still for the settle window,
allocateis asked once, with the eligible regions and their shards, andrebalanceis called with the eligible regions as candidates and the shards of every region whose member is up. That map is wider than the candidates on purpose: it also lists a region registered on an up member that is no candidate — refused over its shard count, or without the type’s role — so that its shards can be proposed for a move onto a candidate. Both built-in strategies propose every one of them —LeastShardAllocationStrategyahead of its threshold check, within its per-pass budget. A custom strategy that weighs only the candidates leaves them where they are.
Either way a pick that is not among the candidates the call was given is
never placed — the coordinator logs it at WARN, naming the pick and the
candidates, once per shard until that shard is placed — and a rebalance
proposal for a shard whose current owner is not up is dropped. So an
allocate call is a question, not a placement: a strategy that keeps
state — a round-robin cursor, a
“last owner” — must not count one as a shard having landed anywhere.
Useful for app-specific rules:
- Pin certain shards to certain nodes — e.g., shards with
IDs < 10 always go to the
coordinator-role nodes. - Affinity / anti-affinity — keep specific shards together, or always apart.
- Capacity-aware — query each node’s metrics, weight by available memory.
class RoleAffinityAllocationStrategy implements AllocationStrategy { constructor(private readonly coordinatorAddrs: Set<string>) {}
allocate(shardId, candidates, currentShards) { if (shardId < 10) { // Pin low-id shards to coordinator nodes const coord = candidates.find(c => this.coordinatorAddrs.has(c.toString())); if (coord) return coord; } return new HashAllocationStrategy().allocate(shardId, candidates, currentShards); }
rebalance() { return new Set(); } // no rebalance for the example}The strategy runs in the coordinator, which is a singleton on the cluster leader. It must be deterministic enough that two coordinators (during a leader-change handover) would converge on the same decision — or at least not undo each other’s work.
Performance
Section titled “Performance”allocate runs once per new shard ID — twice at most while
membership settles — bounded by numShards (default 64). Even an
expensive strategy is fine here.
rebalance runs every rebalanceIntervalMs (default 2 s) once the
set of members that are up has settled. It sees the eligible regions
as candidates and every shard a region on an up member holds — nothing
of a region on a member that is unreachable or still joining. Keep it
under 100 ms or so to avoid blocking the coordinator’s other work.
Picking
Section titled “Picking”For most clusters:
- Default (
HashAllocationStrategy) — start here. Measure. LeastShardAllocationStrategy— switch if the default produces visible hot-spots (one node CPU-saturated while others idle).- Custom — only when neither built-in fits, and you have specific evidence the customization helps.
Don’t reach for a custom strategy preemptively. The built-ins cover ~95 % of use cases.
Where to next
Section titled “Where to next”- Sharding overview — the big picture: how allocation fits with rebalance + handoff.
- Rebalance — the handoff protocol the strategy triggers.
- Remember entities — what happens to entity placement on a respawn.
- Sharded daemon process —
uses
LeastShardAllocationStrategyby default.
