Rust API

server.Server.wait_for_channel

Rust

Python
TypeScript Unavailable
Rust
Go
Java Unavailable
.NET
C++
Swift

Module: server
Declared in: Server
Package: libtmux
Source: crates/libtmux/src/server/channels.rs
Other languages: Python TypeScript Go Java .NET C++Swift

wait_for_channel ( self , channel : &str , within : Duration ) → Result<ChannelWait, Error> method [source] ¶ method [source] ¶ wait_for_channel

Wait for a wait-for channel to be signalled.

The blocking half of Server::signal_channel . Nothing polls: tmux releases the wait when the channel is signalled, so a caller costs one idle client rather than a loop.

This waits for something to *say* it happened. It does not watch a pane, so what signals the channel is the caller's to arrange -- a command ending with `tmux wait-for -S <channel>` is the usual shape.

The channel latches. Signalling one nothing is waiting on is kept, and the next wait returns at once; the latch is one-shot, so a second wait blocks again. One signal releases every waiter present at the time. So signalling before the wait starts is safe, which is what makes this usable for a command that may finish first.

That holds across the supported range. cmd-wait-for.c is identical between 3.5a and 3.7c, and the only changes since 3.2a are an argument table gaining a field, an accessor replacing a direct index, and a local being renamed -- none of them near the flag the latch is kept in. Measured directly on 3.2a, 3.5a, 3.7c and 3.7d.

A wait that runs out of time leaves its client on the channel, because tmux cannot withdraw one and a killed client would eat the channel's next signal. Another wait on the same channel joins that client rather than opening a second, and a signal that releases it with nobody waiting is kept for the next wait, which is where the latch above survives a wait that gave up. The client is this process's, so it ends with Server::shutdown ; it does not count against crate::DispatchLimits , because signalling the channel is itself a dispatch.

within is capped at Server::default_timeout : ask for longer by building the server with a longer timeout.

Errors

Returns an error when tmux refuses the channel name or cannot be reached. Running out of time is ChannelWait::TimedOut rather than an error, so "nothing signalled it" stays distinct from "the command did not get through" -- the caller retries only one of those.

A handle from Server::over_control_mode is refused with crate::ControlModeErrorKind::BlockingCommand : a connection runs one command at a time, and tmux closes a blocking wait-for the moment it queues it, so the wait would neither wait nor let anything else through. Server::signal_channel routes as usual.

Cancel safety

Nothing is lost by a drop, and nothing is left for the next caller to find: the client stays on the channel exactly as it does after ChannelWait::TimedOut , and a signal that releases it is kept for the next wait on this server handle or any clone of it.

A process outside this one is the exception. The signal that releases the parked client is spent in tmux, so a *different* process waiting on the same channel afterwards does not see it; tmux offers no way to take a waiter back out, and forging a replacement signal would release somebody else's wait.

Discussed in Waiting and retrying

In other ports Wait for, signal or lock a channel

Python libtmux.Server.wait_for
TypeScript no equivalent on Server
Go tmux.Server.WaitFor
Java no equivalent on Server
.NET LibTmux.Server.WaitForAsync
C++ libtmux::Server::wait_for
Swift Server.wait(for:)

Examples

Rust Python

use libtmux::ChannelWait;
use std::time::Duration;

// Signalling first is safe: the channel keeps it.
server.signal_channel("ready").await?;
let outcome = server.wait_for_channel("ready", Duration::from_secs(5)).await?;
assert_eq!(outcome, ChannelWait::Signalled);

// The latch is spent, so a second wait runs out of time instead.
let again = server.wait_for_channel("ready", Duration::from_millis(200)).await?;
assert_eq!(again, ChannelWait::TimedOut);

>>> server.new_session(session_name='wait_test')
Session(...)
>>> server.wait_for('test_channel', set_flag=True)

0 declared, 0 inherited