Trait futures::executor::Notify

source · [−]
pub trait Notify: Send + Sync {
    fn notify(&self, id: usize);

    fn clone_id(&self, id: usize) -> usize { ... }

    fn drop_id(&self, id: usize) { ... }
}
Expand description

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

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

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 through task::current while a future is being polled. In that case the instance of Notify passed in to one of the poll_* functions is called with the id passed into the same poll_* function.
  • A Task is itself being cloned. Each Task contains its own id and a handle to the Notify behind it, and the task’s Notify is used to clone the internal id 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.

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.

Implementors