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§
sourcetype Error: AwaitableError
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§
sourcefn try_wait(
&'a self
) -> Result<Self::T, <Self::Error as AwaitableError>::UnboundedError>
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.
Provided Methods§
sourcefn try_wait0(&'a self) -> Result<Self::T, Self::Error>
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.
sourcefn wait(&'a self) -> Self::Twhere
Self::Error: InfallibleUnboundedWait,
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.
sourcefn wait_for(&'a self, limit: Duration) -> boolwhere
Self: VoidAwaitable,
Self::Error: InfallibleUnboundedWait,
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
.
sourcefn wait0(&'a self) -> boolwhere
Self: VoidAwaitable,
Self::Error: InfallibleUnboundedWait,
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
.