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
impl Session
Sourcepub fn subscribe(
&self,
path: impl AsRef<Path>,
options: WatchOptions,
) -> Result<Watch>
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
longPathAwarein its manifest and the machine hasLongPathsEnabledset,CreateFileWis one of the functions Windows lists as no longer carrying aMAX_PATHrestriction, 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 toMAX_PATHbecause 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).
Sourcepub fn answer(&self, watch: WatchId, delay: Option<Duration>)
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).
Sourcepub fn answer_volume_change(
&self,
watch: WatchId,
decision: VolumeChangeDecision,
)
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.