tmux_operation
Own a command independently of an individual wait.
Source and package
- Qualified name
-
tmux_operation - Package
- libtmux_erlang
- Source
- apps/libtmux_erlang/src/tmux_operation.erl
- tmux_operation
-
Description#
start/3submits a validated command through the endpoint's bounded admission. The initiating process owns it.await/2timing out abandons only that wait;cancel/1or owner death retires the client and may leave an unknown tmux outcome. The endpoint acknowledgestransfer/2after monitoring the new owner and before replying to the old owner. The new process does not perform a handshake. Retired results expire after 60 seconds or earlier when the endpoint exceeds 64 retained results or 4 MiB of retained stdout/stderr (oldest evicted first). Closing the endpoint clears its operation results immediately. Each operation accepts at most 16 concurrent waiters; excess waits return too_many_waiters.await_started/2returns lifecycle status once the operation leaves queued; dispatch authorization does not establish a tmux aftereffect.See
completed/0andfailure/0for command outcomes andstate/0for lifecycle status. The job guide shows the complete workflow. Bounded OTP Logger reports correlate outcomes by operation and endpoint generation; see runtime diagnostics for levels, fields and data boundaries.
Members12#
Common operations7#
- status/1 function Read the retained lifecycle state without starting a tmux command. Expired handles return operation_expired. Status is observation of the operation, not evidence that a possibly sent mutation was cancelled.
- await/2 function Wait for a retained result for at most Timeout. An await_timeout removes only this waiter; the operation continues and its handle remains usable. Additional waiters do not become owners. Results preserve outcome and cleanup certainty.
- completed/0 typealias A successful command result. stdout and stderr are separate byte strings; exit_status is zero. stdin_delivered counts bytes accepted by the client pipe, not bytes consumed by tmux. success does not prove a background aftereffect.
- failure/0 typealias A tagged error detail with a stable code and optional certainty/output data. Validation, admission and wait errors may contain only code. Command failures retain available stdout/stderr, stdin_delivered and exit_status. Other keys provide code-specific context. Never infer missing certainty fields.
- start/3 function Submit a validated command under the endpoint's admission limits and return an operation handle. The initiating process owns it. Submission is non-blocking with respect to command completion; the handle does not prove that tmux has executed the command.
- state/0 typealias Observed lifecycle state, without command output. queued includes admission and identity preflight; sent means dispatch authorization, not a proven aftereffect. responded can retain incomplete cleanup; retired releases operation resources. pending certainty means no result yet. The owner is the initiating or transferred process; holding a waiter handle does not change it.
- transfer/2 function Transfer ownership to a live process on this Erlang node. The endpoint installs its new owner monitor before releasing the previous monitor and returns after the swap. The new process performs no handshake. Waiters and ownership remain separate; endpoint ownership does not change.
Other members5#
- await_started/2 function Wait until the operation leaves queued, returning its lifecycle state even if it has already failed or retired. Inspect outcome and cleanup; call
await/2for final command data. Authorization is not proof of a tmux aftereffect. A timeout abandons this wait without cancelling the operation. - cancel/1 function Request cancellation using this handle. Any holder can cancel; only the owner can transfer ownership. Queued work can be cancelled before submission; possibly sent work retires its client and can retain an unknown tmux outcome. Use
await/2for the result and cleanup proof. Never infer rollback or automatically retry a mutation from cancellation alone. already_completed means a response exists; it does not establish complete cleanup. - cleanup/0 typealias complete proves owned client retirement; incomplete or unverified does not.
- outcome/0 typealias Command certainty, separate from resource cleanup. unknown must not trigger an automatic mutation retry.
- t/0 typealias A generation-bound operation handle. Possessing a waiter handle does not transfer ownership.
Guides#
Pages that discuss tmux_operation.