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
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
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
.