Skip to main content

Session

Struct Session 

Source
pub struct Session { /* private fields */ }
Expand description

A client’s connection to a monitor.

Obtained from Monitor::session, which returns it together with the receiver its notifications arrive on.

Cloning is how a client gets the multi-producer submission D-11 requires: every clone submits to the same servicing path and delivers to the same receiver, so several client threads can share one stream without coordinating.

Implementations§

Source§

impl Session

Source

pub fn subscribe( &self, path: impl AsRef<Path>, options: WatchOptions, ) -> Result<Watch>

Watch path, delivering to this session’s receiver.

Registration is asynchronous: this returns as soon as the request is queued, and the watch begins on the monitor’s own servicing path. The returned handle owns the subscription’s lifetime – dropping it cancels – so it must be kept for as long as the client wants notifications.

path reaches Win32 verbatim (D-85). It may be relative, may use forward slashes, and may contain . or .., because this crate does not prepend \\?\ on a caller’s behalf – that prefix selects a different path parsing mode in which none of those resolve.

The consequence worth knowing: a path longer than MAX_PATH opens only by one of two escapes, and only the first is available to a relative path.

  • Long-path opt-in – works for relative and absolute alike. If your application declares longPathAware in its manifest and the machine has LongPathsEnabled set, CreateFileW is one of the functions Windows lists as no longer carrying a MAX_PATH restriction, and that is a property of the call rather than of the shape of the path.
  • The \\?\ prefix – absolute only. Windows states that a relative path is limited to MAX_PATH because the prefix cannot be applied to one: the prefix means “pass this through with minimal modification”, so there is nothing left to resolve it against. That limit is a consequence of the prefix route, not a separate ceiling the opt-in leaves standing.

So a long relative path is fine in a long-path-aware process, and has no escape at all in one that has not opted in.

Measured, not inferred. probe-long-path-aware and probe-long-path-unaware in windows-platform-probes are the same code differing only in whether their manifest declares longPathAware. They open a file through a relative path of 429 characters, from a short current directory, with no prefix. With the opt-in every shape opens; without it every shape is refused with ERROR_PATH_NOT_FOUND while the same shapes at 78 characters open, which is the length refusal rather than a missing file – the probe creates each target first.

The measurement also answers a question the documentation does not. A plausible implementation of the opt-in would be to regularize the path and prepend \\?\, and that prefix is exactly what disables ., .. and forward-slash translation – so a relative path using any of those could have resolved under MAX_PATH and failed over it. It does not. Both shapes resolve past the ceiling exactly as they do below it, so the opt-in lifts the length check without re-parsing, and this crate passing paths verbatim exposes no edge at that boundary.

§Errors

Returns io::ErrorKind::WouldBlock if the notification queue has no room to guarantee this subscription’s registration and cancellation completions (D-33) – backpressure lands here, synchronously, rather than at a later delivery that has no safe way to fail. Returns io::ErrorKind::NotConnected if the monitor has already shut down. A path that cannot be watched is not reported by either of those: whether it can be is not known until the monitor tries, and arrives asynchronously as a Notification::Completion (D-30).

Source

pub fn answer(&self, watch: WatchId, delay: Option<Duration>)

Answer an interactive subscription’s Notification::RetryQuestion (D-27): Some(delay) names the next retry delay, None declines and is counted at the failing operation’s default. Not itself a request with a lifecycle – it is a response to one the crate posed – so it carries no completion and simply does nothing if watch is not currently awaiting an answer (already resolved, already cancelled, or never asked).

Source

pub fn answer_volume_change( &self, watch: WatchId, decision: VolumeChangeDecision, )

Answer a subscription’s Notification::VolumeChanged question (D-78/M12): VolumeChangeDecision::Continue keeps the subscription running against the new volume, VolumeChangeDecision::Stop removes it. Not itself a request with a lifecycle, so it carries no completion and simply does nothing if watch is not currently awaiting an answer.

Source

pub fn is_open(&self) -> bool

Whether the monitor behind this session is still accepting requests.

Trait Implementations§

Source§

impl Clone for Session

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Session

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.