# Streams and live state

Source: https://libtmux.org/en/fsharp/latest/topics/observations/

> Choose a single-result wait, a destructive event stream, or a reconciled mirror.

A captured snapshot is a replayable local observation. A control client's event
stream is ordered, live, and destructive: reading an event consumes it. Do not
use it as though it were an ordinary replayable sequence.

## Choose the observation contract

| Need | Use |
| --- | --- |
| One shell completion or text condition | The appropriate [`Pane.run`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-pane-run/>), [`Pane.sendAndWait`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-pane-sendandwait/>), [`Pane.waitForText`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-pane-waitfortext/>), or [`Pane.waitUntil`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-pane-waituntil/>) operation. |
| React to individual notifications | [`Control.events`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-events/>). |
| Output from one or several panes | [`Control.watchPane`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-watchpane/>) or [`Control.watchPanes`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-watchpanes/>). |
| A maintained captured view of topology | [`Mirror.start`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-mirror-start/>), or [`Mirror.startRefreshing`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-mirror-startrefreshing/>) for periodic refresh during quiet intervals. |

A wait returns one result. A stream transfers responsibility for matching, loss,
termination, and cleanup to its consumer. A mirror reacquires state; it does not
make every tmux property observable through notifications.

## One client has one event consumer

The async enumerables are cold: no records are read until enumeration starts.
The consumer supplies cancellation. [`Control.foldWhile`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-foldwhile/>) and [`Control.iter`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-iter/>) await
one callback at a time and dispose their enumerator while leaving a borrowed
client open.

Watching two panes independently requires independent clients. Use
[`Control.watchPanes`](<https://libtmux.org/en/fsharp/latest/reference/libtmux-fsharp-control-watchpanes/>) to follow several through one stream; each output identifies
its pane, and unrelated events are consumed by that watcher. Acquire the client
for the session that contains the panes.

## Gaps and terminal events matter

A bounded client can report [`TmuxEventsDroppedEvent`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxeventsdroppedevent/>). Its [`OnlyOutput`](<https://libtmux.org/en/csharp/latest/reference/libtmux-tmuxeventsdroppedevent-onlyoutput/>) flag
distinguishes output-only loss from lost notifications. Reacquire current state
when the notifications used to maintain it may be incomplete. A screen capture
can show the present screen, but cannot restore a complete missing output history.

A fast-exiting program can lose terminal output before tmux sends it to a control
client. Prefer the documented completion operation or capture a pane retained
with remain-on-exit when final output matters. An exit event, stream failure,
consumer cancellation, and explicit client closure are different endings.

A mirror reacts to announced changes and can refresh during quiet intervals for
state tmux does not announce. Its anchor-session lifetime remains relevant; it is
not an independent permanent service.

The [streams guide](https://libtmux.org/en/fsharp/latest/guides/streams/) specifies loss, final output, mirror
refresh, and cleanup behavior. See [ownership](https://libtmux.org/en/fsharp/latest/topics/ownership/) before sharing a
client, and [task cancellation](https://libtmux.org/en/fsharp/latest/topics/execution/) before interpreting an interrupted
operation as having no effect.