A connection handle pinned to one qualified control epoch.
submit/3 returns a retained LibTmux.Operation after bounded admission.
It never retries, refreshes, attaches, creates sessions or changes transport.
request_close/1 closes write authority for the entire pinned epoch through
reserved capacity; it does not prove retirement or roll back effects.
start_link/1 explicitly attaches to an existing session. Its host must qualify
the server's effective hooks, aliases and stream writers for the whole lane;
a pinned handle is not authentication against unqualified command output or
arbitrary writes to internal tables. Reads and local selections never attach.
Summary
Types
A positive millisecond budget shared by all stages of one lifecycle or submission call.
A pinned epoch's current phase and identity; retirement and unknown cleanup are distinct.
Explicit attachment policy and bounded startup settings; capacities count slots and timeouts use milliseconds.
A handle pinned to one owner and connection epoch; it never follows a replacement.
Functions
Builds a permanent supervisor child spec without attaching.
Requests closure and waits for proven retirement of the pinned epoch.
Waits for retirement or raises the same structured error.
Explicitly obtains the ready epoch, starting a replacement only after retirement.
Obtains the ready epoch or raises the same structured error.
Requests whole-epoch closure without claiming an operation or metadata slot.
Requests epoch closure or raises the same structured error.
Starts a linked connection and returns {:ok, root, control}.
Reads the pinned epoch's current phase and identity without contacting tmux.
Reads pinned connection status or raises the same structured error.
Admits one request and returns its retained operation handle.
Admits a request or raises the same structured error.
Types
@type call_option() :: {:timeout, pos_integer()}
A positive millisecond budget shared by all stages of one lifecycle or submission call.
@type connection_status() :: %{ epoch: reference() | nil, generation: non_neg_integer(), phase: :starting | :ready | :closing | :retired | :unknown, instance: String.t() | nil }
A pinned epoch's current phase and identity; retirement and unknown cleanup are distinct.
@type start_option() :: {:server, LibTmux.Server.t()} | {:session, {:existing, String.t()}} | {:lane, :host_qualified} | {:timeout, 1..600_000} | {:capacity | :metadata_capacity | :waiter_capacity, 1..256} | {:retention_ms, 1..600_000}
Explicit attachment policy and bounded startup settings; capacities count slots and timeouts use milliseconds.
@opaque t()
A handle pinned to one owner and connection epoch; it never follows a replacement.
Functions
@spec child_spec([start_option()]) :: Supervisor.child_spec()
Builds a permanent supervisor child spec without attaching.
Prepares bounded detached inputs and one lifetime shared by all factory
invocations. Each invocation starts its own configured startup budget.
A restarted nonfresh lifetime returns an inert handle and never attaches
automatically. Proven retirement permits explicit reconnect/2; unknown
cleanup refuses it. Old handles never follow a replacement Root or Manager.
Supervisor.start_child/2 and Supervisor.restart_child/2 return the new
handle as their third info element. After an automatic restart, use
Supervisor.terminate_child/2 followed by Supervisor.restart_child/2 for
fresh info. This does not clear unknown cleanup or authorize replay.
@spec close(t(), [call_option()]) :: :ok | {:error, LibTmux.Error.t()}
Requests closure and waits for proven retirement of the pinned epoch.
timeout defaults to 5000ms. The original budget includes validation and
retirement waiting. Closure still happens if the bounded metadata wait cannot
be admitted. Timeout, overload or lost ownership reports unknown certainty;
it never proves cleanup. :ok requires known native and actor retirement.
The connection supervisor and retained records remain available for explicit reconnect and inspection. This does not stop the supervisor or roll back sibling effects.
@spec close!(t(), [call_option()]) :: :ok
Waits for retirement or raises the same structured error.
@spec reconnect(t(), [call_option()]) :: {:ok, t()} | {:error, LibTmux.Error.t()}
Explicitly obtains the ready epoch, starting a replacement only after retirement.
A ready epoch returns itself. Call close/2 first to require replacement.
The default 5000ms budget covers metadata admission, retirement and startup.
A successful reply pins the acknowledged endpoint even if it becomes stale
before this caller resumes. It never follows a later view or replays work.
Errors report unknown certainty about existing effects. Attachment counts
include the control client; reconnect can attach one replacement client.
@spec reconnect!(t(), [call_option()]) :: t()
Obtains the ready epoch or raises the same structured error.
@spec request_close(t()) :: :ok | {:error, LibTmux.Error.t()}
Requests whole-epoch closure without claiming an operation or metadata slot.
Repeated requests for the same closing or proven-retired generation return
:ok. Success is a request or previously known retirement, not a cleanup
acknowledgement. A replacement Manager or epoch is never followed.
@spec request_close!(t()) :: :ok
Requests epoch closure or raises the same structured error.
@spec start_link([start_option()]) :: {:ok, pid(), t()} | {:error, LibTmux.Error.t()}
Starts a linked connection and returns {:ok, root, control}.
Require server: %LibTmux.Server{}, session: {:existing, "$id"} and
lane: :host_qualified. No session is created. The attachment is visible in
tmux's client counts and can update session state. no-output,ignore-size
suppresses pane output and excludes this client from window sizing.
timeout defaults to 5000ms and accepts 1..600000ms. One budget covers input
preparation, Root startup, bootstrap, ready waiting and handoff. A fresh
factory returns a ready handle. Runtime failures return a structured error;
invalid trusted options raise ArgumentError. Ordinary OTP links remain:
an asynchronous fatal Root exit can terminate a non-trapping caller.
Failed startup fences its lifetime and requests exact-Root cleanup. Error details distinguish observed Root exit from a kill request; unknown native cleanup is never success. OTP can await Root exit after its initialization timer expires, so a strict wall-clock caller-return bound remains unqualified.
Optional capacity, metadata_capacity and waiter_capacity default to 32
and accept 1..256. retention_ms defaults to 60000 and accepts 1..600000.
Ready connections buffer at most 64 KiB or 128 stdout chunks behind the
reader. Overflow closes the whole epoch with resource_limit; it never
replays commands. These receive limits do not cap borrowed-server memory.
@spec status(t()) :: {:ok, connection_status()} | {:error, LibTmux.Error.t()}
Reads the pinned epoch's current phase and identity without contacting tmux.
@spec status!(t()) :: connection_status()
Reads pinned connection status or raises the same structured error.
@spec submit(t(), LibTmux.Control.Request.t(), [call_option()]) :: {:ok, LibTmux.Operation.t()} | {:error, LibTmux.Error.t()}
Admits one request and returns its retained operation handle.
timeout defaults to 5000ms and covers validation, admission, queueing,
writes and replies under one monotonic deadline. Request binaries are
detached before publication. Invalid input, overload or stale context before
admission returns a no-write error. Every successful admission returns its
Operation, even if its context disappears before publication. Inspect that
handle for the eventual canonical result or an explicit lost-context error.
Closing the connection can affect sibling operations. Command replies do not prove external program exit. Caller timeout does not authorize replay.
@spec submit!(t(), LibTmux.Control.Request.t(), [call_option()]) :: LibTmux.Operation.t()
Admits a request or raises the same structured error.