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