1 #![deny(missing_docs, missing_debug_implementations)]
2 #![doc(html_root_url = "https://docs.rs/tokio-executor/0.1.9")]
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 
54 extern crate crossbeam_utils;
55 extern crate futures;
56 
57 mod enter;
58 mod error;
59 mod executor;
60 mod global;
61 pub mod park;
62 mod typed;
63 
64 pub use enter::{enter, exit, Enter, EnterError};
65 pub use error::SpawnError;
66 pub use executor::Executor;
67 pub use global::{set_default, spawn, with_default, DefaultExecutor, DefaultGuard};
68 pub use typed::TypedExecutor;
69