futures_core/task/context.rs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132
use core::fmt;
use executor::Executor;
use task::{Waker, LocalMap};
/// Information about the currently-running task.
///
/// Contexts are always tied to the stack, since they are set up specifically
/// when performing a single `poll` step on a task.
pub struct Context<'a> {
waker: &'a Waker,
pub(crate) map: &'a mut LocalMap,
executor: Option<&'a mut Executor>,
}
impl<'a> Context<'a> {
/// Create a new task context without the ability to `spawn`.
///
/// This constructor should *only* be used for `no_std` contexts, where the
/// standard `Executor` trait is not available.
pub fn without_spawn(map: &'a mut LocalMap, waker: &'a Waker) -> Context<'a> {
Context { waker, map, executor: None }
}
/// Get the [`Waker`](::task::Waker) associated with the current task.
///
/// The waker can subsequently be used to wake up the task when some
/// event of interest has happened.
pub fn waker(&self) -> &Waker {
self.waker
}
fn with_parts<'b, F, R>(&'b mut self, f: F) -> R
where F: FnOnce(&'b Waker, &'b mut LocalMap, Option<&'b mut Executor>) -> R
{
// reborrow the executor
let executor: Option<&'b mut Executor> = match self.executor {
None => None,
Some(ref mut e) => Some(&mut **e),
};
f(self.waker, self.map, executor)
}
/// Produce a context like the current one, but using the given waker
/// instead.
///
/// This advanced method is primarily used when building "internal
/// schedulers" within a task, where you want to provide some customized
/// wakeup logic.
pub fn with_waker<'b>(&'b mut self, waker: &'b Waker) -> Context<'b> {
self.with_parts(|_, map, executor| {
Context { map, executor, waker }
})
}
/// Produce a context like the current one, but using the given task locals
/// instead.
///
/// This advanced method is primarily used when building "internal
/// schedulers" within a task.
pub fn with_locals<'b>(&'b mut self, map: &'b mut LocalMap)
-> Context<'b>
{
self.with_parts(move |waker, _, executor| {
Context { map, executor, waker }
})
}
}
if_std! {
use std::boxed::Box;
use Future;
use never::Never;
impl<'a> Context<'a> {
/// Create a new task context.
///
/// Task contexts are equipped with:
///
/// - Task-local data
/// - A means of waking the task
/// - A means of spawning new tasks, i.e. an [executor]()
pub fn new(map: &'a mut LocalMap, waker: &'a Waker, executor: &'a mut Executor) -> Context<'a> {
Context { waker, map, executor: Some(executor) }
}
/// Get the default executor associated with this task, if any
///
/// This method is useful primarily if you want to explicitly handle
/// spawn failures.
pub fn executor(&mut self) -> &mut Executor {
self.executor
.as_mut().map(|x| &mut **x)
.expect("No default executor found: std-using futures contexts must provide an executor")
}
/// Spawn a future onto the default executor.
///
/// # Panics
///
/// This method will panic if the default executor is unable to spawn
/// or does not exist.
///
/// To handle executor errors, use [executor()](self::Context::executor)
/// instead.
pub fn spawn<F>(&mut self, f: F)
where F: Future<Item = (), Error = Never> + 'static + Send
{
self.executor()
.spawn(Box::new(f)).unwrap()
}
/// Produce a context like the current one, but using the given executor
/// instead.
///
/// This advanced method is primarily used when building "internal
/// schedulers" within a task.
pub fn with_executor<'b>(&'b mut self, executor: &'b mut Executor)
-> Context<'b>
{
self.with_parts(move |waker, map, _| {
Context { map, executor: Some(executor), waker }
})
}
}
}
impl<'a> fmt::Debug for Context<'a> {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
f.debug_struct("Context")
.finish()
}
}