tmux_server
Open tmux endpoints and execute explicit command values.
Source and package
- tmux_server
-
Description#
open/1validates an absolute socket path and the executable/server versions. It never creates a tmux server or attaches a control client. Each command rechecks the observed Linux process incarnation before dispatch. Replacement between that observation and a later client connection remains possible; same_connection requests are rejected until persistent dispatch qualifies.start_owned/1creates a separate private daemon and returns an ownership token forstop_owned/1. The ownership guide explains caller death, application shutdown and namespace cleanup.Use
with_server/2orwith_owned/2for a callback scope. They attempt cleanup after its return or exception and preserve both outcomes if cleanup fails.The calling process owns the endpoint.
close/1cancels queued work, retires its one-shot clients and preserves the borrowed server. Cleanup failure remains explicit and keeps the supervised owner alive. Successful close is idempotent during the 60-second handle retention period. Separatetmux_controlattachments receive an invalidation notice and begin their own retirement. Close those attachments explicitly to prove their native cleanup. Command results preserve stdout, stderr and status; cancellation after dispatch cannot undo remote effects. Clients explicitly select tmux's UTF-8 mode so Unicode and the identity probe's tab do not depend on the caller's locale. Command-specific escaping still applies to raw command output.Use
snapshot/1to capture a graph fortmux_snapshotandtmux_select. Usetmux_operationfor non-blocking submission and explicit waits; the job guide explains ownership and cleanup.
Members22#
Collections and queries1#
- snapshot/1 function Capture a complete immutable graph with default capture limits. Performs I/O. See
snapshot/2for bounds, consistency and conflict errors.
Common operations11#
- stop_owned/1 function Stop the daemon and endpoint associated with a
ownership/0token. Performs I/O and returns ok only after endpoint/client/helper retirement and namespace cleanup are proved. It never sends kill-server to a socket path. - command/3 function Execute one validated command and await its result. Performs I/O. The result preserves stdout, stderr, exit status and cleanup certainty. Use
tmux_operation:start/3to submit without blocking this caller. A timeout or cancellation cannot reverse effects that may already have reached tmux. Values from domain command builders keep their captured endpoint origin. Another endpoint returns different_owner with submitted = false before any native preflight or execution. Raw commands do not carry that origin. - version/1 function Return the daemon version observed when the endpoint opened. This reads owner state and does not execute a fresh version command or qualify another tmux release.
- start_owned/1 function Start an empty owned daemon in a fresh private Linux socket directory. Performs I/O and waits for bounded startup; no session or attached observer is created. Returns an ordinary endpoint and a separate
ownership/0token. The caller owns the daemon lifetime: caller death orstop_owned/1retires its helper tree.close/1only closes the endpoint and preserves the daemon. - bind/2 function Explicitly read current fields from this server and register the new value. For sessions, physical windows and panes, the read uses the stable ID and discards the supplied field observations. This explicit call accepts an edited target; ordinary actions require its captured target association to match and reject mismatches before dispatch. The returned row carries a new private observation association; see
tmux_model. It provides no atomic identity check. Window-link binding checks its session/index and expected physical window. A replaced or missing membership returns stale_link. This observed preflight does not make a later action atomic. - with_owned/2 function Start an owned daemon, run a callback in the calling process, then stop it. Performs
start_owned/1and token-basedstop_owned/1around the callback. With successful cleanup, returns {ok, Value} or re-raises the original callback exception. A returned error tuple is an ordinary callback value. Startup failure passes through without invoking the callback. - close/1 function Retire this endpoint's operations and one-shot clients, preserving the borrowed tmux server. Returns ok only after their cleanup completes; incomplete cleanup remains an explicit error. Closing an already closed retained handle is idempotent. The initiator controls endpoint lifetime. Separate control attachments are invalidated and asked to retire; use
tmux_control:close/1before this call to verify those clients' cleanup too. - with_server/2 function Open a borrowed endpoint, run a callback in the calling process, then close it. Performs the same I/O as
open/1andclose/1; the borrowed daemon survives. Startup failure passes through without invoking the callback. - open/1 function Open a borrowed socket endpoint and start its supervised library owner. The caller owns that handle. This probes the executable, daemon version and observed Linux process incarnation; it never starts a tmux server or attaches a control client. Pass an absolute socket_path and optionally an executable.
- scope_failure/0 typealias Both callback and cleanup evidence when a scope cannot prove retirement. primary is the callback value or its exception class, reason and original stack. cleanup preserves the operational error or a separate cleanup exception. server permits
close/1reconciliation; owned scopes also include ownership forstop_owned/1. Retain these handles until cleanup is resolved. - snapshot/2 function Capture the server's sessions, physical windows, window links and panes.
Other members10#
- capture_options/0 typealias Capture bounds, hydration strategy and consistency request. Atomic capture is unsupported.
- command_options/0 typealias Command options: deadline_ms defaults to 2500, max_stdout to 1 MiB, max_stderr to 64 KiB, stdin to an empty binary and identity to observed. The deadline includes admission, preflight and execution. stdin is limited to 256 KiB; stdin plus the rendered argument reservation must also fit 256 KiB. Each endpoint admits at most 64 operations and 256 KiB of command payload; exhaustion returns busy. same_connection is recognized but unsupported.
- hydration/0 typealias Capture text/bytes with one framed scan per entity (batched, the default), or one field per physical row (isolated). Both retain complete graph coverage and interval semantics. Each command has the same 1 MiB stdout bound; isolated can distribute large entity output across commands at greater source cost. See
snapshot/2andtmux_query:explain/1. - open_options/0 typealias An explicit absolute socket endpoint and optional absolute tmux executable path.
- origin/1 function Return the registered opaque origin for this open endpoint. The token provides library provenance and generation checks, not authorization against trusted Erlang code. It is not a portable identifier.
- owned_options/0 typealias Owned startup options. The finite startup budget defaults to 2500 milliseconds.
- ownership/0 typealias Opaque ownership token for
stop_owned/1. An ordinary endpoint or row origin does not convey this token. Trusted code can pass it to another process. - state/0 typealias Endpoint resource summary. owner is the supervised endpoint process, not its initiating caller. operations and command_bytes count active admission leases; active_bytes reserves output capacity. Retired results are bounded separately by retained_results and result_bytes. These are accounting limits, not VM heap measurements. generation identifies this endpoint handle's lifetime.
- status/1 function Read the endpoint owner's lifecycle and resource summary. This contacts the library owner, not tmux, and does not refresh captured rows.
- t/0 typealias A supervised borrowed-endpoint handle bound to an owner generation and admission state.
Guides#
Pages that discuss tmux_server.
In other ports#
A tmux server
| Language | Equivalent |
|---|---|
| Python | libtmux |
| Ruby | Lib |
| Lua | libtmux |
| PowerShell | Lib This cmdlet constructs a shared .NET LibTmux.Server handle without contacting tmux. |
| Julia | Lib Server describes an endpoint without contacting tmux. Read its hierarchy with snapshot. |
| Elixir | Lib Server describes an existing server by executable and socket. It neither connects nor reserves the server’s identity. |
| Haskell | No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing. |
| TypeScript | server |
| Rust | server |
| Go | tmux |
| Java | io |
| Clojure | libtmux Opens a closeable Java server client for an explicit endpoint. Acquisitions return persistent maps with explicit Java references for effects. |
| Kotlin | io |
| Scala | io |
| C# | Lib |
| F# | Lib This F# module provides functions over the shared .NET LibTmux.Server type. |
| C++ | libtmux:: |
| Swift | Server |
| OCaml | Libtmux A client is a live, generation-bound server connection. Endpoint describes a socket without connecting; closing a client releases its resources. |
| Perl | Lib Construction records connection settings without tmux I/O. Optional LibTmux::Async::Server returns standard Future results for operations. |
No equivalent is recorded in Common Lisp.