[−][src]Struct futures::task::Task
A handle to a "task", which represents a single lightweight "thread" of execution driving a future to completion.
In general, futures are composed into large units of work, which are then spawned as tasks onto an executor. The executor is responsible for polling the future as notifications arrive, until the future terminates.
This is obtained by the task::current
function.
FAQ
Why does Task
not implement Eq
and Hash
?
A valid use case for Task
to implement these two traits has not been
encountered.
Usually, this question is asked by someone who wants to store a Task
instance in a HashSet
. This seems like an obvious way to implement a
future aware, multi-handle structure; e.g. a multi-producer channel.
In this case, the idea is that whenever a start_send
is called on one of
the channel's send handles, if the channel is at capacity, the current task
is stored in a set. Then, when capacity is available, a task is removed from
the set and notified.
The problem with this strategy is that multiple Sender
handles can be used
on the same task. In this case, when the second handle is used and the task
is stored in a set, there already is an entry. Then, when the first
handle is dropped, this entry is cleared, resulting in a dead lock.
See here for more discussion.
Methods
impl Task
[src]
pub fn notify(&self)
[src]
Indicate that the task should attempt to poll its future in a timely fashion.
It's typically guaranteed that, after calling notify
, poll
will
be called at least once subsequently (unless the future has terminated).
If the task is currently polling its future when notify
is called, it
must poll the future again afterwards, ensuring that all relevant
events are eventually observed by the future.
pub fn is_current(&self) -> bool
[src]
intended to be removed, see docs for details
Returns true
when called from within the context of the task.
In other words, the task is currently running on the thread calling the
function. Note that this is currently, and has historically, been
implemented by tracking an id
on every instance of Spawn
created.
When a Spawn
is being polled it stores in thread-local-storage the id
of the instance, and then task::current
will return a Task
that also
stores this id.
The intention of this function was to answer questions like "if I
notify
this task, is it equivalent to task::current().notify()
?"
The answer "yes" may be able to avoid some extra work to block the
current task, such as sending a task along a channel or updating a
stored Task
somewhere. An answer of "no" typically results in doing
the work anyway.
Unfortunately this function has been somewhat buggy in the past and is
not intended to be supported in the future. By simply matching id
the
intended question above isn't accurately taking into account, for
example, unpark events (now deprecated, but still a feature). Thus many
old users of this API weren't fully accounting for the question it was
intended they were asking.
This API continues to be implemented but will in the future, e.g. in the
0.1.x series of this crate, eventually return false
unconditionally.
It is intended that this function will be removed in the next breaking
change of this crate. If you'd like to continue to be able to answer the
example question above, it's recommended you use the
will_notify_current
method.
If you've got questions about this though please let us know! We'd like to learn about other use cases here that we did not consider.
Panics
This function will panic if no current future is being polled.
pub fn will_notify_current(&self) -> bool
[src]
This function is intended as a performance optimization for structures
which store a Task
internally.
The purpose of this function is to answer the question "if I notify
this task is it equivalent to task::current().notify()
". An answer
"yes" may mean that you don't actually need to call task::current()
and store it, but rather you can simply leave a stored task in place. An
answer of "no" typically means that you need to call task::current()
and store it somewhere.
As this is purely a performance optimization a valid implementation for
this function is to always return false
. A best effort is done to
return true
where possible, but false negatives may happen. Note that
this function will not return a false positive, however.
Panics
This function will panic if no current future is being polled.
Trait Implementations
Auto Trait Implementations
impl Unpin for Task
impl Send for Task
impl Sync for Task
impl !UnwindSafe for Task
impl !RefUnwindSafe for Task
Blanket Implementations
impl<T> From<T> for T
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
[src]
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,