LeanLmdb.BatchWriter (lean_lmdb v0.3.0)

View Source

Optional supervised group-commit coordinator for one LMDB environment.

Submissions are validated and value-codec payloads are encoded in the caller before queue admission. Calls return only after their atomic LMDB transaction commits or fails. The queue and each native batch are bounded by operation count and encoded bytes.

A caller timeout does not cancel work already accepted by the writer. flush/2 is a commit barrier; sync/2 first drains accepted work and then forces an environment checkpoint according to LeanLmdb.sync/1.

An unexpected commit-worker exit has an unknown outcome: the transaction may already have committed. In-flight waiters receive :batch_writer_unknown_outcome, queued waiters fail, no work is retried, and the writer terminates. Its transient child specification restarts on this abnormal exit but not after normal stop/2. Forced supervisor shutdown uses ordinary OTP exit semantics and does not promise to drain volatile work.

One writer is scoped to one environment in one BEAM. Other BEAM OS processes may run independent queues; LMDB still serializes their write transactions. Status and crash state contain bounded counters and handles, never queued payloads after fatal waiter resolution.

Summary

Types

option()

Functions

delete(writer, database, key, timeout \\ 5000)

Submits one idempotent delete through the writer.

flush(writer, timeout \\ 5000)

Waits until work accepted before this call has committed or failed.

put(writer, database, key, value, timeout \\ 5000)

Submits one put through the writer.

start_link(options)

Starts a BatchWriter for exactly one environment.

status(writer, timeout \\ 5000)

Returns bounded queue and commit counters without exposing payloads.

stop(writer, timeout \\ 5000)

Stops accepting work, drains prior submissions, and stops normally.

submit(writer, operations, timeout \\ 5000)

Submits one atomic operation list and waits for its LMDB commit result.

sync(writer, timeout \\ 5000)

Drains prior work and then forces the environment to durable storage.

Types

option()

@type option() ::
  {:environment, LeanLmdb.Environment.t()}
  | {:name, GenServer.name()}
  | {:max_batch_operations, 1..10000}
  | {:max_batch_bytes, pos_integer()}
  | {:max_queue_operations, pos_integer()}
  | {:max_queue_bytes, pos_integer()}
  | {:max_wait_ms, 0..60000}

Functions

delete(writer, database, key, timeout \\ 5000)

@spec delete(
  GenServer.server(),
  LeanLmdb.Database.t() | LeanLmdb.CodecDatabase.t(),
  binary(),
  timeout()
) :: :ok | {:error, LeanLmdb.reason()}

Submits one idempotent delete through the writer.

flush(writer, timeout \\ 5000)

@spec flush(GenServer.server(), timeout()) :: :ok | {:error, LeanLmdb.reason()}

Waits until work accepted before this call has committed or failed.

put(writer, database, key, value, timeout \\ 5000)

@spec put(
  GenServer.server(),
  LeanLmdb.Database.t() | LeanLmdb.CodecDatabase.t(),
  binary(),
  term(),
  timeout()
) :: :ok | {:error, LeanLmdb.reason()}

Submits one put through the writer.

start_link(options)

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

Starts a BatchWriter for exactly one environment.

status(writer, timeout \\ 5000)

@spec status(GenServer.server(), timeout()) :: map()

Returns bounded queue and commit counters without exposing payloads.

stop(writer, timeout \\ 5000)

@spec stop(GenServer.server(), timeout()) :: :ok | {:error, LeanLmdb.reason()}

Stops accepting work, drains prior submissions, and stops normally.

submit(writer, operations, timeout \\ 5000)

@spec submit(GenServer.server(), [LeanLmdb.batch_operation()], timeout()) ::
  :ok | {:error, LeanLmdb.reason()}

Submits one atomic operation list and waits for its LMDB commit result.

sync(writer, timeout \\ 5000)

@spec sync(GenServer.server(), timeout()) :: :ok | {:error, LeanLmdb.reason()}

Drains prior work and then forces the environment to durable storage.