tmux_snapshot (libtmux for Erlang v0.0.1)
View SourceRead an immutable captured graph without performing tmux I/O.
Server-wide lists use numeric ID order. Window links retain every membership,
including multiple indexes for the same window in one session. Session windows
are unique in first-link order; panes within a window use pane index order.
related/3 accepts a row from this snapshot and returns a
tagged result. A row from another observation cannot silently select a
relationship in this one.
metadata/1 records source calls, the capture interval,
endpoint generation and the observed server incarnation. Captures span
commands and are not atomic. Values remain readable after their endpoint
closes; actions still validate the row's registered origin. Coverage
distinguishes unloaded data from an empty collection and unavailable fields
from known absence. See the graph guide for physical windows and
session memberships.
Summary
Types
Per-entity coverage. Use require/2 to check requirements before evaluation.
Collection completeness, field availability and relationship completeness. A loaded field can hold a known value or known absence; inspect the row to distinguish them. not_loaded never means empty, and unavailable never means known absence. Completeness is relative to the captured source collection.
Capture identity and provenance. id identifies this snapshot, origin its registered endpoint and generation the endpoint lifetime. model_version names the row representation. graph describes relationship coverage, not atomicity.
Source-query capture diagnostics. candidate_count is the deduplicated candidate identity count before local residuals and limits. pushed_down records a nontrivial native condition in the plan, not proof that its command ran: empty collections can skip it. source_calls records actual capture commands. The flag does not mean the full predicate was translated. attempt starts at one and increases only for an explicitly requested retry.
A collection, field or complete relationship needed for faithful local evaluation.
One completed capture command and its stdout byte count. started and finished are local monotonic microseconds, not wall-clock timestamps. The interval includes identity preflight and command completion; it is not an atomic read.
An immutable captured graph with identity, indexes, coverage and source intervals.
Functions
Return per-collection, field and relationship coverage. Loaded values, known absence, not_loaded and unavailable capabilities have distinct meanings. Performs no I/O.
Look up a row in this capture by ID, or a session/index/window tuple for a window link. Returns none for a known missing identity and a tagged coverage error for an unloaded collection. Performs no I/O.
Return capture identity, server generation, source calls, capabilities and read interval metadata. Does not refresh the graph or imply atomic capture.
Return unique captured physical panes in numeric ID order without I/O.
related/3 orders panes within a window by pane index.
Traverse a complete captured relationship without I/O. To-many relations return lists; to-one relations return a row or known absence. The input row must belong to this snapshot. Unloaded relations and mismatched rows return tagged errors.
Check every declared collection/field/relationship requirement before local evaluation. Returns an incomplete_snapshot error with missing requirements when the capture cannot answer faithfully. Performs no I/O, even on empty data.
Return a captured collection by schema entity. Performs no I/O. An unloaded collection raises incomplete_snapshot rather than appearing empty.
Return captured sessions in numeric ID order. Performs no I/O and raises incomplete_snapshot when that collection was not captured.
Return every captured membership, ordered by numeric session ID, index and window ID. Multiple links to the same physical window are preserved. Performs no I/O; link identity belongs to this snapshot.
Return unique captured physical windows in numeric ID order. Performs no I/O.
Use window_links/1 for session-relative membership and indexes.
Types
-type coverage() :: #{tmux_schema:entity() => entity_coverage()}.
Per-entity coverage. Use require/2 to check requirements before evaluation.
-type entity_coverage() :: #{collection := complete | not_loaded, fields := #{atom() => loaded | not_loaded | unavailable}, relations := #{atom() => complete | not_loaded}}.
Collection completeness, field availability and relationship completeness. A loaded field can hold a known value or known absence; inspect the row to distinguish them. not_loaded never means empty, and unavailable never means known absence. Completeness is relative to the captured source collection.
-type metadata() :: #{id := reference(), origin := reference(), model_version := 2, graph := complete | partial, generation => reference(), endpoint => #{socket_path := binary()}, server_instance => tmux_identity:t(), tmux_version => tmux_version:t(), capture_started => integer(), capture_finished => integer(), time_unit => microsecond, source_calls => [source_call()], observed_bytes => non_neg_integer(), consistency => observed, hydration => tmux_server:hydration(), capabilities => #{field_schema := 1, identity := observed, capture := observed}, query => query_metadata(), atom() => term()}.
Capture identity and provenance. id identifies this snapshot, origin its registered endpoint and generation the endpoint lifetime. model_version names the row representation. graph describes relationship coverage, not atomicity.
Live captures include endpoint, observed server_instance, tmux_version,
monotonic capture bounds in time_unit, source_calls, observed stdout bytes and
capabilities. Those fields can be absent in internally constructed partial
captures. Query captures also include query_metadata/0. Opaque references
and process identities are local values, not portable wire identifiers.
hydration records the requested tmux_server:hydration/0 strategy; source_calls
shows which commands actually ran, including any schema-driven fallback.
-type query_metadata() :: #{candidate_count := non_neg_integer(), pushed_down := boolean(), attempt := 1 | 2, consistency := observed}.
Source-query capture diagnostics. candidate_count is the deduplicated candidate identity count before local residuals and limits. pushed_down records a nontrivial native condition in the plan, not proof that its command ran: empty collections can skip it. source_calls records actual capture commands. The flag does not mean the full predicate was translated. attempt starts at one and increases only for an explicitly requested retry.
-type requirement() :: {collection, tmux_schema:entity()} | {field | relation, tmux_schema:entity(), atom()}.
A collection, field or complete relationship needed for faithful local evaluation.
-type source_call() :: #{command := binary(), args := [binary()], started := integer(), finished := integer(), stdout_bytes := non_neg_integer()}.
One completed capture command and its stdout byte count. started and finished are local monotonic microseconds, not wall-clock timestamps. The interval includes identity preflight and command completion; it is not an atomic read.
-opaque t()
An immutable captured graph with identity, indexes, coverage and source intervals.
Functions
Return per-collection, field and relationship coverage. Loaded values, known absence, not_loaded and unavailable capabilities have distinct meanings. Performs no I/O.
-spec get(tmux_schema:entity(), term(), t()) -> {ok, tmux_model:row()} | none | {error, map()}.
Look up a row in this capture by ID, or a session/index/window tuple for a window link. Returns none for a known missing identity and a tagged coverage error for an unloaded collection. Performs no I/O.
Return capture identity, server generation, source calls, capabilities and read interval metadata. Does not refresh the graph or imply atomic capture.
-spec panes(t()) -> [tmux_model:pane()].
Return unique captured physical panes in numeric ID order without I/O.
related/3 orders panes within a window by pane index.
-spec require([requirement()], t()) -> ok | {error, map()}.
Check every declared collection/field/relationship requirement before local evaluation. Returns an incomplete_snapshot error with missing requirements when the capture cannot answer faithfully. Performs no I/O, even on empty data.
-spec rows(tmux_schema:entity(), t()) -> [tmux_model:row()].
Return a captured collection by schema entity. Performs no I/O. An unloaded collection raises incomplete_snapshot rather than appearing empty.
-spec sessions(t()) -> [tmux_model:session()].
Return captured sessions in numeric ID order. Performs no I/O and raises incomplete_snapshot when that collection was not captured.
-spec window_links(t()) -> [tmux_model:window_link()].
Return every captured membership, ordered by numeric session ID, index and window ID. Multiple links to the same physical window are preserved. Performs no I/O; link identity belongs to this snapshot.
-spec windows(t()) -> [tmux_model:window()].
Return unique captured physical windows in numeric ID order. Performs no I/O.
Use window_links/1 for session-relative membership and indexes.