Trait rsevents_extra::Awaitable

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

    // Required methods
    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>;

    // Provided methods
    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 rsevents abstraction over all types that can be awaited, implemented by types in this crate.

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§

source

type T

The type yielded by the Awaitable type on a successful wait

source

type Error: AwaitableError

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§

source

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

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.

source

fn try_wait_for(&'a self, limit: Duration) -> Result<Self::T, Self::Error>

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§

source

fn try_wait0(&'a self) -> Result<Self::T, Self::Error>

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.

source

fn wait(&'a self) -> Self::Twhere Self::Error: InfallibleUnboundedWait,

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.

source

fn wait_for(&'a self, limit: Duration) -> boolwhere Self: VoidAwaitable, Self::Error: InfallibleUnboundedWait,

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.

source

fn wait0(&'a self) -> boolwhere Self: VoidAwaitable, Self::Error: InfallibleUnboundedWait,

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§