Server.wait_for_channel

Description#

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.