Trait rsevents::Awaitable

source · [−]
pub trait Awaitable<'a> {
    type T;
    type Error: AwaitableError;

    fn try_wait(
        &'a self
    ) -> Result<Self::T, <Self::Error as AwaitableError>::UnboundedError>;
    fn try_wait_for(&'a self, limit: Duration) -> Result<Self::T, Self::Error>;

    fn try_wait0(&'a self) -> Result<Self::T, Self::Error> { ... }
    fn wait(&'a self) -> Self::T
    where
        Self::Error: InfallibleUnboundedWait,
    { ... }
    fn wait_for(&'a self, limit: Duration) -> bool
    where
        Self: VoidAwaitable,
        Self::Error: InfallibleUnboundedWait,
    { ... }
    fn wait0(&'a self) -> bool
    where
        Self: VoidAwaitable,
        Self::Error: InfallibleUnboundedWait,
    { ... }
}
Expand description

The basic interface for waiting on void awaitable types

This is a unified trait that is used by rsevents and downstream dependent crates implementing synchronization primitives atop of rsevents to expose a single interface for waiting on an object either indefinitely or for a bounded length of time.

Types implementing Awaitable<T = (), Error = TimeoutError> unlock a much simpler Awaitable api for end users, that omits error handling and replaces timeout errors with boolean results.

Required Associated Types

The type yielded by the Awaitable type on a successful wait

The type yielded by the Awaitable type in case of an error, also specifying whether or not an unbounded Awaitable::wait() returns any error at all.

Required Methods

Waits on the Awaitable type, blocking efficiently until it becomes available. Returns the awaited type T (if it isn’t ()) or an error indicating a wait issue. Does not time out.

Waits on the Awaitable type until it becomes available or the timeout period described by limit elapses, in which case a timeout error is returned.

Provided Methods

Attempt to obtain the Awaitable type T in a potentially lock-free, wait-free manor, returning a timeout error if it is not available. This call may have side effects beyond merely returning the current state and must not be considered the equivalent of a test() or peek() function.

This function should be overridden by Awaitable implementations that can offer a streamlined version of try_wait_for() for hard-coded zero timeout.

Blocks until the Awaitable type and its associated type T become available. Like try_wait() but bypasses error handling.

Only available if the Awaitable implementation implements InfallibleUnboundedWait, i.e. does not return any errors except on timeout.

Attempts a bounded wait on the the Awaitable type. Like try_wait_for() but returns true if the Awaitable was originally available or if it became so within the specified duration and false otherwise.

Only available if Awaitable::Error implements InfallibleUnboundedWait (i.e. does not return any errors except on timeout) and has a void return type T.

Attempts to obtain the Awaitable in a potentially lock-free, wait-free manner, returning a timeout error if it’s currently unavailable. Like try_wait0() but returns true if the Awaitable was available and obtained or false otherwise.

This call may have side effects beyond merely returning the current state and must not be considered the equivalent of a test() or peek() function.

Note that this may not be the same as calling Awaitable::wait_for() with a Duration of zero, as the implementing type may use a different approach to ensure that the calling thread does not block.

Only available if Awaitable:Error implements InfallibleUnboundedWait (i.e. does not return any errors except on timeout) and has a void return type T.

Implementors