Control
A qualified control connection for scoped and managed execution.
Source and package
- Qualified name
-
LibTmux .Control - Module
- LibTmux
- Package
- libtmux
- Source
- lib/libtmux/control.ex
-
Description#
Start with
with_connection/2to own startup and cleanup around a callback. Useexecute/3to obtain a command outcome after wire retirement and record reclamation. Canonical:failed,:skippedand:unknownoutcomes remain values, including from bang functions; acknowledgement does not prove external program completion. See the managed control guide.A successful scope returns
{:ok, callback_value}after proven cleanup.LibTmux.Control.ScopeFailurepreserves the callback outcome when cleanup fails.LibTmux.Control.ExecutionErrorcarries the operation handle and recovery context for errors after admission.Starting a connection explicitly attaches to an existing session. The host must qualify effective hooks, aliases and stream writers for its lifetime;
lane: :host_qualifieddeclares that work without performing it. Each handle stays pinned to one epoch. Pinning does not authenticate unqualified output or defend against arbitrary writes to internal tables. Local selections never attach, and commands never replay, refresh or change transport.For independently retained results, use
submit/3andLibTmux.Operation. Awaiting a retained result does not reclaim its record. See the advanced execution guide for explicit ownership.request_close/1closes write authority for the entire epoch through reserved capacity; it neither proves retirement nor rolls back effects.Discussed in Read values, execute explicitly
Members20#
Common operations8#
- close/2 function Requests closure and waits for proven retirement of the pinned epoch.
- reconnect/2 function Explicitly obtains the ready epoch, starting a replacement only after retirement.
- submit/3 function Admits one request and returns its retained operation handle.
- child_spec/1 function Builds a permanent supervisor child spec without attaching.
- execute/3 function Executes one qualified request, returning its result after wire retirement and record reclamation. Repeated successful calls need no manual forget.
- request_close/1 function Requests whole-epoch closure without claiming an operation or metadata slot.
- start_link/1 function Starts a linked connection and returns
{:ok, root, control}. - with_connection/2 function Runs a callback with one connection and owns its native and supervisor cleanup.
Other members12#
- call_option/0: call
_option () :: {:timeout, pos_integer ()} typealias A positive millisecond budget shared by all stages of one lifecycle or submission call. - close!/2 function Waits for retirement or raises the same structured error.
- connection_status/0: connection
_status () :: %{ epoch: reference() | nil, generation: non_neg (), phase: :starting | :ready | :closing | :retired | :unknown, instance: String_integer .t () | nil } typealias A pinned epoch's current phase and identity; retirement and unknown cleanup are distinct. - execute!/3 function Executes and reclaims as in
execute/3; raises API/context errors, preserving canonical failures as values. - reconnect!/2 function Obtains the ready epoch or raises the same structured error.
- request_close!/1 function Requests epoch closure or raises the same structured error.
- scope_option/0: scope
_option () :: start_option () | {:cleanup_timeout, 1..950} typealias Startup options plus a separate cleanup allowance of 1..950ms, default 950ms; callback duration has no library timer. - start_option/0: start
_option () :: {:server, LibTmux ()} | {:session, {:existing, String.Server .t .t ()}} | {:lane, :host_qualified} | {:timeout, 1..600_000} | {:capacity | :metadata_capacity | :waiter_capacity, 1..256} | {:retention_ms, 1..600_000} typealias Explicit attachment policy and bounded startup settings; capacities count slots and timeouts use milliseconds. - status!/1 function Reads pinned connection status or raises the same structured error.
- status/1 function Reads the pinned epoch's current phase and identity without contacting tmux.
- submit!/3 function Admits a request or raises the same structured error.
- t/0 typealias A handle pinned to one owner and connection epoch; it never follows a replacement.