# server.Server.wait_for_channel

- **Module:** server.Server
- **Package:** libtmux
- **Language:** Rust
- **Kind:** method
- **Source:** https://github.com/libtmux/libtmux-rs/blob/f0e37052c232636b61d095817046e6bfc8f2ca40/crates/libtmux/src/server/channels.rs#L220
- **Page:** https://libtmux.org/en/rs/latest/reference/server-server-wait_for_channel/

```
server.Server.wait_for_channel(self, channel: &str, within: Duration) -> Result<ChannelWait, Error>
```

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.

## Example

```rust
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);
```