Waiting and retrying

After sending input or starting a process, wait for the state your next step requires. Pane interaction covers waiting for screen text. This page covers arbitrary conditions and tmux’s named $wait-for signal channels.

Polling a condition¶

Polling checks a condition repeatedly until it succeeds or a deadline expires. Set a deadline and choose an interval that limits unnecessary tmux commands.

Helper: libtmux.test.retry_until(fn, seconds=, interval=)

Where it lives: src/libtmux/test/ in the main package; raises !WaitTimeout.

Examples¶

def is_window_up(pane, name):
    return any(w.window_name == name for w in pane.window.session.windows)

libtmux.test.retry_until(lambda: is_window_up(pane, "build"), seconds=5.0)

tmux’s own $wait-for channel¶

Use $tmux wait-for -S <channel> to signal and tmux wait-for <channel> to block until signalled. This avoids repeated screen captures when the command can announce its own completion:

Signal a channel with mServer.wait_for and set_flag=True. Call the same method without that flag to wait for the signal.

server.new_session(session_name="work")
server.wait_for("built", set_flag=True)  # signal
server.wait_for("built")                 # block until signalled

tmux remembers a signal sent before a waiter starts. The next wait on that channel returns immediately, so completion is not lost when the command finishes first.

A raw wait-for client can exit zero when the server dies, as well as when the channel is signalled. Verify server liveness when a lost server must be treated as a failed task.

Use a channel name specific to the task. A remembered signal can otherwise satisfy an unrelated later wait.