A retained operation handle pinned to its original owner, tables and epoch.
result/1 and status/1 read local retained values. await/2 owns a separate
bounded waiter; its timeout never stops the operation. stop/1 requests
closure of the operation's entire connection epoch, including siblings.
It does not roll back effects or prove native cleanup.
Canonical results carry outcome, certainty and evidence. Completed,
failed, skipped and unknown outcomes remain values, including in bang APIs.
Bang functions raise only API or metadata errors. A command reply is distinct
from wire retirement and arbitrary program exit.
Normal reconnect preserves retained records until forget or expiry. Owner replacement loses those tables; a handle never follows a replacement view.
Summary
Types
A qualified command reply, independently of wire retirement or program completion.
A positive millisecond budget for one waiter or record-reclamation call.
The immutable canonical outcome; failed, skipped and unknown outcomes remain values.
A canonical no-write outcome, with the reason it was skipped before dispatch.
Retained wire progress and the canonical result, or nil while no outcome is established.
A retained owner-bound operation handle; it is not a command result or a reservation.
An epoch closed without enough evidence to classify the operation's effects.
Wire progress for this operation; retired wire does not prove connection cleanup.
Functions
Waits for a canonical result under one positive millisecond timeout.
Waits or raises API errors; canonical failed, skipped and unknown outcomes remain values.
Requests exact-record reclamation with a default 5000ms timeout.
Forgets the retained record or raises the same structured error.
Returns a canonical result, :pending, or a retained-context error.
Reads a result or :pending; raises API errors, preserving all canonical outcomes.
Reads retained wire state and canonical result without contacting tmux.
Reads retained status or raises the same structured error.
Requests closure of the pinned epoch through reserved capacity.
Requests epoch closure or raises the same structured error.
Types
@type command_result() :: %{ outcome: :completed | :failed, certainty: :acknowledged, evidence: :command_reply, guard: LibTmux.Protocol.guard_id(), lines: [binary()] }
A qualified command reply, independently of wire retirement or program completion.
@type option() :: {:timeout, pos_integer()}
A positive millisecond budget for one waiter or record-reclamation call.
@type result() :: command_result() | skipped_result() | unknown_result()
The immutable canonical outcome; failed, skipped and unknown outcomes remain values.
@type skipped_result() :: %{
outcome: :skipped,
certainty: :no_write,
evidence: :cancelled | :timeout | :epoch_closed
}
A canonical no-write outcome, with the reason it was skipped before dispatch.
Retained wire progress and the canonical result, or nil while no outcome is established.
@opaque t()
A retained owner-bound operation handle; it is not a command result or a reservation.
@type unknown_result() :: %{
outcome: :unknown,
certainty: :unknown,
evidence: :epoch_closed
}
An epoch closed without enough evidence to classify the operation's effects.
@type wire() :: :unpublished | :unsent | :writing | :awaiting | :closing | :retired
Wire progress for this operation; retired wire does not prove connection cleanup.
Functions
@spec await(t(), [option()]) :: {:ok, result()} | {:error, LibTmux.Error.t()}
Waits for a canonical result under one positive millisecond timeout.
The default is 5000ms. Every call claims an independent bounded waiter slot,
including terminal operations; use result/1 for immediate inspection.
Completed waiter copies survive record reclamation until this caller reads
them. Timeout, overload and caller death affect only this waiter.
Waits or raises API errors; canonical failed, skipped and unknown outcomes remain values.
@spec forget(t(), [option()]) :: :ok | {:error, LibTmux.Error.t()}
Requests exact-record reclamation with a default 5000ms timeout.
Wire-active records cannot be forgotten. An owner-accepted request remains owned after caller timeout. Successful reclamation invalidates this record handle while preserving already-accepted waiter copies.
Forgets the retained record or raises the same structured error.
@spec result(t()) :: :pending | {:ok, result()} | {:error, LibTmux.Error.t()}
Returns a canonical result, :pending, or a retained-context error.
Reads a result or :pending; raises API errors, preserving all canonical outcomes.
@spec status(t()) :: {:ok, status()} | {:error, LibTmux.Error.t()}
Reads retained wire state and canonical result without contacting tmux.
Reads retained status or raises the same structured error.
@spec stop(t()) :: :ok | {:error, LibTmux.Error.t()}
Requests closure of the pinned epoch through reserved capacity.
Returns :ok for an already wire-retired operation or an accepted closure
request, and {:error, error} otherwise. Closure can affect sibling work;
success does not prove retirement or change the canonical result. A stale
handle cannot revoke a replacement epoch.
@spec stop!(t()) :: :ok
Requests epoch closure or raises the same structured error.