Struct WatchHandle 

pub struct WatchHandle<P> { /* private fields */ }

RAII handle returned by watch(). Holds a subscription lease and reads the property live from the state store. Dropping the handle starts the grace period — the UPnP subscription persists for 50ms so it can be reacquired cheaply on the next frame.

Not Clone — each handle is one subscription hold.

The value is live, not a snapshot

Self::value reads the store on every call, so a handle acquired once and held across many events keeps returning the current value. There is no need to re-watch() to refresh it; a handle is a lease on the subscription, and reading through it is the same read get() performs.

The value is therefore returned by clone rather than by reference: the store sits behind an RwLock shared with the event worker, and handing out a borrow into it would either hold that lock for the handle’s whole lifetime or alias a value the worker is free to replace. P is a small Clone property (a u8, a bool, a few Strings at worst), so the copy is cheaper than the lock it would otherwise pin.

Example

// Watch returns a handle — hold it to keep the subscription alive
let volume = speaker.volume.watch()?;

if let Some(v) = volume.value() {
    println!("Volume: {}%", v.value());
}

// Hold the same handle across events — value() re-reads each time
for _event in system.iter() {
    println!("Volume now: {:?}", volume.value());
}

// Dropping the handle starts the 50ms grace period
drop(volume);

Implementations

impl<P> WatchHandle<P>

pub fn mode(&self) -> WatchMode

Returns the watch mode (Events, Polling, or CacheOnly).

pub fn value(&self) -> Option<P>

Returns the property’s current value, read live from the state store.

Costs one read-lock acquisition plus a clone of P — not free, unlike the frozen field this replaced, but it is the same cost as get() and it is what makes the handle a live view instead of a stale snapshot.

Returns None if no value has been observed yet, or if the value has since become unreachable (a speaker that left the topology, or a PerCoordinator property whose group was dissolved).

pub fn has_value(&self) -> bool

Returns true if a value is currently available from the store.

Also a live read: this can go from false to true as the first event arrives, without the handle being re-acquired.

pub fn has_realtime_events(&self) -> bool

Returns true if real-time UPnP events are active.

Trait Implementations

impl<P: Debug> Debug for WatchHandle<P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.