control.ControlSender.subscribe

On this page

Module: control
Declared in: ControlSender
Package: libtmux
Source: crates/libtmux/src/control.rs

subscribe ( self , name : &str , watching : &Subscription , format : &str ) → Result<(), Error> method [source] ¶ method [source] ¶ subscribe

Ask tmux to report a format whenever it changes.

tmux answers with Event::SubscriptionChanged carrying the name given here, so one connection can hold several subscriptions and tell them apart. Reporting is coalesced to at most once a second, so this says what a value became and not every step it took getting there.

A name already in use is replaced rather than added to.

Errors

Returns an error when the connection has closed, tmux refuses the subscription, or the name is empty or contains a colon.

Examples

use libtmux::control::{ControlMode, Event, Subscription};

let guard = libtmux::test::TestServer::new().await?;
let session = guard.server().new_session("watched").await?;
let (commands, mut events) = ControlMode::attach(guard.server(), session.id())
    .await?
    .split();

commands
    .subscribe("title", &Subscription::Session, "#{session_name}")
    .await?;

// The first report arrives without anything having changed, which is
// what makes a subscription usable for reading the value as well.
while let Some(event) = events.next_event().await {
    if let Event::SubscriptionChanged { name, value, .. } = event {
        assert_eq!(name.as_str()?, "title");
        assert_eq!(value.as_str()?, "watched");
        break;
    }
}

commands.unsubscribe("title").await?;
events.shutdown().await?;

0 declared, 0 inherited