tokio_executor/
lib.rs

1#![deny(missing_docs, missing_debug_implementations)]
2#![doc(html_root_url = "https://docs.rs/tokio-executor/0.1.10")]
3
4//! Task execution related traits and utilities.
5//!
6//! In the Tokio execution model, futures are lazy. When a future is created, no
7//! work is performed. In order for the work defined by the future to happen,
8//! the future must be submitted to an executor. A future that is submitted to
9//! an executor is called a "task".
10//!
11//! The executor is responsible for ensuring that [`Future::poll`] is called
12//! whenever the task is notified. Notification happens when the internal
13//! state of a task transitions from *not ready* to *ready*. For example, a
14//! socket might have received data and a call to `read` will now be able to
15//! succeed.
16//!
17//! This crate provides traits and utilities that are necessary for building an
18//! executor, including:
19//!
20//! * The [`Executor`] trait spawns future object onto an executor.
21//!
22//! * The [`TypedExecutor`] trait spawns futures of a specific type onto an
23//!   executor. This is used to be generic over executors that spawn futures
24//!   that are either `Send` or `!Send` or implement executors that apply to
25//!   specific futures.
26//!
27//! * [`enter`] marks that the current thread is entering an execution
28//!   context. This prevents a second executor from accidentally starting from
29//!   within the context of one that is already running.
30//!
31//! * [`DefaultExecutor`] spawns tasks onto the default executor for the current
32//!   context.
33//!
34//! * [`Park`] abstracts over blocking and unblocking the current thread.
35//!
36//! # Implementing an executor
37//!
38//! Executors should always implement `TypedExecutor`. This usually is the bound
39//! that applications and libraries will use when generic over an executor. See
40//! the [trait documentation][`TypedExecutor`] for more details.
41//!
42//! If the executor is able to spawn all futures that are `Send`, then the
43//! executor should also implement the `Executor` trait. This trait is rarely
44//! used directly by applications and libraries. Instead, `tokio::spawn` is
45//! configured to dispatch to type that implements `Executor`.
46//!
47//! [`Executor`]: trait.Executor.html
48//! [`TypedExecutor`]: trait.TypedExecutor.html
49//! [`enter`]: fn.enter.html
50//! [`DefaultExecutor`]: struct.DefaultExecutor.html
51//! [`Park`]: park/index.html
52//! [`Future::poll`]: https://docs.rs/futures/0.1/futures/future/trait.Future.html#tymethod.poll
53
54extern crate crossbeam_utils;
55extern crate futures;
56
57mod enter;
58mod error;
59mod executor;
60mod global;
61pub mod park;
62mod typed;
63
64pub use enter::{enter, exit, Enter, EnterError};
65pub use error::SpawnError;
66pub use executor::Executor;
67pub use global::{set_default, spawn, with_default, DefaultExecutor, DefaultGuard};
68pub use typed::TypedExecutor;