Mini-percolator for cross-shard multi-key operations.
Provides atomic execution of commands that span multiple shards using per-key locking through Raft consensus. Only involved keys are locked; the rest of each shard operates normally.
Modes
- Same-shard -- all keys hash to the same shard. The execute function is called directly with zero overhead (no locking, no intent).
- Quorum cross-shard -- keys span multiple shards. The protocol is: lock (ordered by shard index) -> write intent -> execute -> delete intent -> unlock.
- Async cross-shard -- returns a CROSSSLOT error with a helpful message suggesting hash tags or quorum mode.
Usage
CrossShardOp.execute(
[{source_key, :read_write}, {dest_key, :write}],
fn store -> ...command logic using unified store... end,
intent: %{command: :smove, keys: %{source: src, dest: dst}}
)The execute_fn receives a unified store map that routes operations to the
correct shard based on key. The store has the same interface as command
handlers use, so existing command logic works unchanged.
Summary
Functions
Executes a multi-key operation, handling same-shard and cross-shard cases.
Types
Functions
@spec execute([key_with_role()], (map() -> term()), keyword()) :: term()
Executes a multi-key operation, handling same-shard and cross-shard cases.
Parameters
keys_with_roles-- list of{key, role}tuples. Role is:read,:write, or:read_write.execute_fn-- function receiving a unified store map and executing the actual command logic. The store routes operations to the correct shard based on key. Must return the command result.opts-- keyword options::intent-- intent map for crash recovery (required for cross-shard):namespace-- namespace prefix for durability lookup (optional, defaults to extracting from first key)
Returns
The result of execute_fn, or {:error, "CROSSSLOT ..."} for async
cross-shard operations.