[−][src]Trait futures::executor::Notify
A trait which represents a sink of notifications that a future is ready to make progress.
This trait is provided as an argument to the Spawn::*_notify
family of
functions. It's transitively used as part of the Task::notify
method to
internally deliver notifications of readiness of a future to move forward.
An instance of Notify
has one primary method, notify
, which is given a
contextual argument as to what's being notified. This contextual argument is
also provided to the Spawn::*_notify
family of functions and can be used
to reuse an instance of Notify
across many futures.
Instances of Notify
must be safe to share across threads, and the methods
be invoked concurrently. They must also live for the 'static
lifetime,
not containing any stack references.
Required methods
fn notify(&self, id: usize)
Indicates that an associated future and/or task are ready to make progress.
Typically this means that the receiver of the notification should arrange for the future to get poll'd in a prompt fashion.
This method takes an id
as an argument which was transitively passed
in from the original call to Spawn::*_notify
. This id can be used to
disambiguate which precise future became ready for polling.
Panics
Since unpark
may be invoked from arbitrary contexts, it should
endeavor not to panic and to do as little work as possible. However, it
is not guaranteed not to panic, and callers should be wary. If a panic
occurs, that panic may or may not be propagated to the end-user of the
future that you'd otherwise wake up.
Provided methods
fn clone_id(&self, id: usize) -> usize
This function is called whenever a new copy of id
is needed.
This is called in one of two situations:
- A
Task
is being created throughtask::current
while a future is being polled. In that case the instance ofNotify
passed in to one of thepoll_*
functions is called with theid
passed into the samepoll_*
function. - A
Task
is itself being cloned. EachTask
contains its own id and a handle to theNotify
behind it, and the task'sNotify
is used to clone the internalid
to assign to the new task.
The id
returned here will be stored in the Task
-to-be and used later
to pass to notify
when the Task::notify
function is called on that
Task
.
Note that typically this is just the identity function, passing through
the identifier. For more unsafe situations, however, if id
is itself a
pointer of some kind this can be used as a hook to "clone" the pointer,
depending on what that means for the specified pointer.
fn drop_id(&self, id: usize)
All instances of Task
store an id
that they're going to internally
notify with, and this function is called when the Task
is dropped.
This function provides a hook for schemes which encode pointers in this
id
argument to deallocate resources associated with the pointer. It's
guaranteed that after this function is called the Task
containing this
id
will no longer use the id
.