# LibTmux.Control

- **Module:** LibTmux
- **Package:** libtmux
- **Language:** Elixir
- **Kind:** struct
- **Source:** https://github.com/libtmux/libtmux-elixir/blob/66b9b1c3f3f3186428abdfda2c76f5cf87446710/lib/libtmux/control.ex#L1
- **Page:** https://libtmux.org/en/elixir/latest/reference/libtmux-control/

A qualified control connection for scoped and managed execution.

Start with `with_connection/2` to own startup and cleanup around a callback.
Use `execute/3` to obtain a command outcome after wire retirement and record
reclamation. Canonical `:failed`, `:skipped` and `:unknown` outcomes remain
values, including from bang functions; acknowledgement does not prove
external program completion. See the [managed control guide](managed-control.html).

A successful scope returns `{:ok, callback_value}` after proven cleanup.
`LibTmux.Control.ScopeFailure` preserves the callback outcome when cleanup
fails. `LibTmux.Control.ExecutionError` carries 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_qualified` declares 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/3` and `LibTmux.Operation`.
Awaiting a retained result does not reclaim its record. See the
[advanced execution guide](advanced-execution.html) for explicit ownership.
`request_close/1` closes write authority for the entire epoch through reserved
capacity; it neither proves retirement nor rolls back effects.

## Members

### Common operations

- [`close/2`](/en/elixir/latest/reference/libtmux-control-close-2/) (function): Requests closure and waits for proven retirement of the pinned epoch.
- [`reconnect/2`](/en/elixir/latest/reference/libtmux-control-reconnect-2/) (function): Explicitly obtains the ready epoch, starting a replacement only after retirement.
- [`submit/3`](/en/elixir/latest/reference/libtmux-control-submit-3/) (function): Admits one request and returns its retained operation handle.
- [`child_spec/1`](/en/elixir/latest/reference/libtmux-control-child_spec-1/) (function): Builds a permanent supervisor child spec without attaching.
- [`execute/3`](/en/elixir/latest/reference/libtmux-control-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`](/en/elixir/latest/reference/libtmux-control-request_close-1/) (function): Requests whole-epoch closure without claiming an operation or metadata slot.
- [`start_link/1`](/en/elixir/latest/reference/libtmux-control-start_link-1/) (function): Starts a linked connection and returns `{:ok, root, control}`.
- [`with_connection/2`](/en/elixir/latest/reference/libtmux-control-with_connection-2/) (function): Runs a callback with one connection and owns its native and supervisor cleanup.

### Other members

- [`call_option/0`](/en/elixir/latest/reference/libtmux-control-call_option-0/) (typealias): A positive millisecond budget shared by all stages of one lifecycle or submission call.
- [`close!/2`](/en/elixir/latest/reference/libtmux-control-close-bang-2/) (function): Waits for retirement or raises the same structured error.
- [`connection_status/0`](/en/elixir/latest/reference/libtmux-control-connection_status-0/) (typealias): A pinned epoch's current phase and identity; retirement and unknown cleanup are distinct.
- [`execute!/3`](/en/elixir/latest/reference/libtmux-control-execute-bang-3/) (function): Executes and reclaims as in `execute/3`; raises API/context errors, preserving canonical failures as values.
- [`reconnect!/2`](/en/elixir/latest/reference/libtmux-control-reconnect-bang-2/) (function): Obtains the ready epoch or raises the same structured error.
- [`request_close!/1`](/en/elixir/latest/reference/libtmux-control-request_close-bang-1/) (function): Requests epoch closure or raises the same structured error.
- [`scope_option/0`](/en/elixir/latest/reference/libtmux-control-scope_option-0/) (typealias): Startup options plus a separate cleanup allowance of 1..950ms, default 950ms; callback duration has no library timer.
- [`start_option/0`](/en/elixir/latest/reference/libtmux-control-start_option-0/) (typealias): Explicit attachment policy and bounded startup settings; capacities count slots and timeouts use milliseconds.
- [`status!/1`](/en/elixir/latest/reference/libtmux-control-status-bang-1/) (function): Reads pinned connection status or raises the same structured error.
- [`status/1`](/en/elixir/latest/reference/libtmux-control-status-1/) (function): Reads the pinned epoch's current phase and identity without contacting tmux.
- [`submit!/3`](/en/elixir/latest/reference/libtmux-control-submit-bang-3/) (function): Admits a request or raises the same structured error.
- [`t/0`](/en/elixir/latest/reference/libtmux-control-t-0/) (typealias): A handle pinned to one owner and connection epoch; it never follows a replacement.