Shared helpers for distributed read/write operations.
Extracts common patterns used across SuperCache.KeyValue, SuperCache.Queue,
SuperCache.Stack, and SuperCache.Struct for:
- Determining cluster mode (
distributed?/0) - Applying writes with replication (
apply_write/3) - Routing writes to the primary node (
route_write/4) - Routing reads with
:local/:primary/:quorummodes (route_read/5) - Checking local partition ownership (
has_partition?/1) - Reading from the primary node (
read_primary/4) - Reading with quorum consensus (
read_quorum/4)
Quorum reads
Quorum reads use Task.async with early termination — as soon as a majority
of replicas agree on a result, remaining tasks are killed. This is more
efficient than Task.async_stream which always waits for all tasks to
complete before computing consensus.
Summary
Functions
Applies a batch of write operations with the configured replication strategy.
Returns true when the cluster is running in distributed mode.
Returns true if the current node holds a replica (primary or secondary)
for the given partition index.
Reads from the primary replica for the given partition.
Reads from all replicas and returns the result that achieves quorum (majority).
Routes a read operation according to the requested read mode.
Routes a write operation to the primary replica for the given partition.
Functions
@spec apply_write(non_neg_integer(), term(), put: term(), delete: term(), delete_match: term(), delete_all: term() ) :: :ok | {:error, term()}
Applies a batch of write operations with the configured replication strategy.
- Strong replication (
:strong): delegates toThreePhaseCommit.commit/2for atomic distributed commits via the WAL-based 3PC protocol. - Async / sync replication: applies each operation to local storage first,
then replicates to replica nodes via
Replicator.
Operations
Each operation is a tuple:
| Operation | Description |
|---|---|
{:put, record} | Insert or update a record |
{:delete, key} | Delete a record by key |
{:delete_match, pattern} | Delete records matching a pattern |
{:delete_all, _} | Delete all records in the partition |
Returns
:okon success{:error, reason}when 3PC commit fails (strong mode only)
@spec distributed?() :: boolean()
Returns true when the cluster is running in distributed mode.
Inlined by the compiler for hot-path performance.
@spec has_partition?(non_neg_integer()) :: boolean()
Returns true if the current node holds a replica (primary or secondary)
for the given partition index.
@spec read_primary(module(), atom(), [term()], non_neg_integer()) :: term()
Reads from the primary replica for the given partition.
If the current node is the primary, the function is applied locally.
Otherwise, an :erpc.call is made to the primary node.
@spec read_quorum(module(), atom(), [term()], non_neg_integer()) :: term()
Reads from all replicas and returns the result that achieves quorum (majority).
Uses Task.async with early termination: as soon as a majority of replicas
agree on a result, remaining tasks are killed immediately. This avoids waiting
for slow replicas once quorum is satisfied.
If no result reaches quorum, falls back to the primary node's result.
Routes a read operation according to the requested read mode.
Read modes
:local— read from the local node. If the local node does not hold a replica, automatically escalates to:primary.:primary— read from the primary replica.:quorum— read from all replicas and return the majority result.
Parameters
caller— the module that owns the function being calledfun— the function name (atom)args— the function arguments (list)partition_idx— the partition indexopts— keyword list, supports:read_mode(default:local)
Returns
The return value of the called function.
@spec route_write(module(), atom(), [term()], non_neg_integer()) :: term()
Routes a write operation to the primary replica for the given partition.
If the current node is the primary, the function is applied locally.
Otherwise, an :erpc.call is made to the primary node.
Parameters
caller— the module that owns the function being called (replaces__MODULE__)fun— the function name (atom)args— the function arguments (list)partition_idx— the partition index used to look up the primary node
Returns
The return value of the called function, or raises on :erpc failure.