Struct futures::Task [−] [src]

pub struct Task {
    // some fields omitted
}

A structure representing one "task", or thread of execution throughout the lifetime of a set of futures.

It's intended that futures are composed together to form a large "task" of futures which is driven as a whole throughout its lifetime. This task is persistent for the entire lifetime of the future until its completion, carrying any local data and such.

Currently tasks serve two primary purposes:

  • They're used to drive futures to completion, e.g. executors (more to be changed here soon).
  • They store task local data. That is, any task can contain any number of pieces of arbitrary data which can be accessed at a later date. The data is owned and carried in the task itself, and TaskData handles are used to access the internals.

This structure is likely to expand more customizable functionality over time! That is, it's not quite done yet...

Methods

impl Task
[src]

fn new() -> Task

Creates a new task ready to drive a future.

fn insert<A>(&mut self, a: A) -> TaskData<A> where A: Any + Send + 'static

Inserts a new piece of task-local data into this task, returning a reference to it.

Ownership of the data will be transferred to the task, and the data will be destroyed when the task itself is destroyed. The returned value can be passed to the Task::{get, get_mut} methods to get a reference back to the original data.

Note that the returned handle is cloneable and copyable and can be sent to other futures which will be associated with the same task. All futures will then have access to this data when passed the reference back.

fn insert_notify<A>(&mut self, a: A) -> TaskNotifyData<A> where A: Any + Send + Sync + 'static

dox

fn get<A>(&self, data: &TaskData<A>) -> &A

Get a reference to the task-local data inside this task.

This method should be passed a handle previously returned by Task::insert. That handle, when passed back into this method, will retrieve a reference to the original data.

Panics

This method will panic if data does not belong to this task. That is, if another task generated the data handle passed in, this method will panic.

fn get_mut<A>(&mut self, data: &TaskData<A>) -> &mut A

Get a mutable reference to the task-local data inside this task.

This method should be passed a handle previously returned by Task::insert. That handle, when passed back into this method, will retrieve a reference to the original data.

Panics

This method will panic if data does not belong to this task. That is, if another task generated the data handle passed in, this method will panic.

fn notify(&mut self)

During the Future::schedule method, notify to the task that a value is immediately ready.

This method, more optimized than TaskHandle::notify, will inform the task that the future which is being scheduled is immediately ready to be polled again.

fn handle(&self) -> &TaskHandle

Gets a handle to this task which can be cloned to a piece of Send+'static data.

This handle returned can be used to notify the task that a future is ready to get polled again. The returned handle implements the Clone trait and all clones will refer to this same task.

Note that if data is immediately ready then the Task::notify method should be preferred.

fn scoped(&mut self) -> ScopedTask

dox

fn run(self, future: Box<Future<Item=(), Error=()>>)

Consumes this task to run a future to completion.

This function will consume the task provided and the task will be used to execute the future provided until it has been completed. The future wil be poll'ed until it is resolved, at which point the Result<(), ()> will be discarded.

The future will be polled on the threads that events arrive on. That is, this method does not attempt to control which thread a future is polled on.

Panics

Currently, if poll panics, then this method will propagate the panic to the thread that poll was called on. This is bad and it will change.