Anoma.Node.Transaction.Shard (Anoma v0.35.0)

I am the Shard module.

I manage a partition of the distributed key-value store, handling requests for reserving slots, reading, and writing specific keys at specific heights.

Public API

I provide the following public functionality:

Key Concepts

  • Cell: A cell of a shard, contains all the information required for a shard.
  • Synchronous Reads: Read requests (read/3) block the caller until resolved. Resolution may be delayed internally if blocked by watermarks or preceding write reservations. Read completion releases the specific read reservation.

Summary

Types

key()

The key in the key-value store.

startup_options()
t()

I am the state of the Shard GenServer.

Functions

advance_watermark(shard_pid, key, h_write)

I advance the write watermark for a given key.

backup_state(shard_pid)

I trigger a backup of the shard's internal state to Mnesia.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

read(shard_pid, key, height)

I am the read function for the Shard module.

reserve(shard_pid, key, height)

I am the reserve function for the Shard module. Use me to reserve a read or write at a specific key at a specific height.

retract(shard_pid, key, height, pid)

I retract a potential read on a shard.

start_link(args)

I am the start_link function for the Shard module.

unreserve(shard_pid, key, height)

I release a write reservation for a given key at a given height.

write(shard_pid, key, value, height)

I am the write function for the Shard module.

Types

key()

@type key() :: [binary()]

The key in the key-value store.

startup_options()

@type startup_options() ::
  {:node_id, String.t()}
  | {:inital_kv,
     %{
       required(key()) => %{
         required(Anoma.Node.Transaction.Shard.Cell.height()) => any()
       }
     }}
  | {:id, atom()}

t()

@type t() :: %Anoma.Node.Transaction.Shard{
  cells: %{
    required(Anoma.Node.Transaction.Shard.Cell.height()) =>
      Anoma.Node.Transaction.Shard.Cell.t()
  },
  id: atom(),
  node_id: String.t()
}

I am the state of the Shard GenServer.

Fields

  • :id - The identifier for this shard.
  • :node_id - The ID of the node this shard belongs to.
  • :cells - The cell of a shard, containing and KV information.

Functions

advance_watermark(shard_pid, key, h_write)

@spec advance_watermark(
  GenServer.server(),
  key(),
  Anoma.Node.Transaction.Shard.Cell.height()
) :: :ok

I advance the write watermark for a given key.

This is an asynchronous operation.

backup_state(shard_pid)

@spec backup_state(GenServer.server()) :: :ok | {:error, any()}

I trigger a backup of the shard's internal state to Mnesia.

This is a synchronous operation.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

read(shard_pid, key, height)

@spec read(GenServer.server(), key(), Anoma.Node.Transaction.Shard.Cell.height()) ::
  {:ok, any()} | :absent | {:error, :not_reserved}

I am the read function for the Shard module.

I perform a synchronous read request for a key at a specific height. The caller blocks until the read can be resolved (potentially waiting for watermarks) and receives the result directly. Returns {:ok, value}, :absent, or an error tuple.

reserve(shard_pid, key, height)

@spec reserve(GenServer.server(), key(), Anoma.Node.Transaction.Shard.Cell.height()) ::
  :ok | {:error, :reserving_write_under_write_watermark | :occupied}

I am the reserve function for the Shard module. Use me to reserve a read or write at a specific key at a specific height.

Reservations exist to inform the KV store that a value will be written at a specific height at some point in the future. If I know that an empty entry will be written to, then an immediate read will have to wait until the write occurs.

I request a reservation on a specific key at a given height. Capabilities can be :read, :write, or :read_write. I return :ok on success, or an error tuple.

retract(shard_pid, key, height, pid)

@spec retract(
  GenServer.server(),
  key(),
  Anoma.Node.Transaction.Shard.Cell.height(),
  pid()
) :: :ok

I retract a potential read on a shard.

I am useful when a specific pid may have requested a read that is no longer relevant.

start_link(args)

@spec start_link([startup_options()]) :: GenServer.on_start()

I am the start_link function for the Shard module.

I start and link a Shard process, register it using the provided id, and initialize its KV state based on initial_kv options.

unreserve(shard_pid, key, height)

@spec unreserve(GenServer.server(), key(), Anoma.Node.Transaction.Shard.Cell.height()) ::
  :ok

I release a write reservation for a given key at a given height.

This is an asynchronous operation primarily used for rollbacks of failed transactions.

write(shard_pid, key, value, height)

@spec write(
  GenServer.server(),
  key(),
  any(),
  Anoma.Node.Transaction.Shard.Cell.height()
) :: :ok

I am the write function for the Shard module.

I write a value for a key at a specific height, requiring a prior reserve call with :write capability for this {key, height}. I return :ok on success, or an error tuple.