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
//! A batteries included runtime for applications using Tokio. //! //! Applications using Tokio require some runtime support in order to work: //! //! * A [reactor] to drive I/O resources. //! * An [executor] to execute tasks that use these I/O resources. //! * A [timer] for scheduling work to run after a set period of time. //! //! While it is possible to setup each component manually, this involves a bunch //! of boilerplate. //! //! [`Runtime`] bundles all of these various runtime components into a single //! handle that can be started and shutdown together, eliminating the necessary //! boilerplate to run a Tokio application. //! //! Most applications wont need to use [`Runtime`] directly. Instead, they will //! use the [`run`] function, which uses [`Runtime`] under the hood. //! //! Creating a [`Runtime`] does the following: //! //! * Spawn a background thread running a [`Reactor`] instance. //! * Start a [`ThreadPool`] for executing futures. //! * Run an instance of [`Timer`] **per** thread pool worker thread. //! //! The thread pool uses a work-stealing strategy and is configured to start a //! worker thread for each CPU core available on the system. This tends to be //! the ideal setup for Tokio applications. //! //! A timer per thread pool worker thread is used to minimize the amount of //! synchronization that is required for working with the timer. //! //! # Usage //! //! Most applications will use the [`run`] function. This takes a future to //! "seed" the application, blocking the thread until the runtime becomes //! [idle]. //! //! ```rust //! # extern crate tokio; //! # extern crate futures; //! # use futures::{Future, Stream}; //! use tokio::net::TcpListener; //! //! # fn process<T>(_: T) -> Box<Future<Item = (), Error = ()> + Send> { //! # unimplemented!(); //! # } //! # fn dox() { //! # let addr = "127.0.0.1:8080".parse().unwrap(); //! let listener = TcpListener::bind(&addr).unwrap(); //! //! let server = listener.incoming() //! .map_err(|e| println!("error = {:?}", e)) //! .for_each(|socket| { //! tokio::spawn(process(socket)) //! }); //! //! tokio::run(server); //! # } //! # pub fn main() {} //! ``` //! //! In this function, the `run` function blocks until the runtime becomes idle. //! See [`shutdown_on_idle`][idle] for more shutdown details. //! //! From within the context of the runtime, additional tasks are spawned using //! the [`tokio::spawn`] function. Futures spawned using this function will be //! executed on the same thread pool used by the [`Runtime`]. //! //! A [`Runtime`] instance can also be used directly. //! //! ```rust //! # extern crate tokio; //! # extern crate futures; //! # use futures::{Future, Stream}; //! use tokio::runtime::Runtime; //! use tokio::net::TcpListener; //! //! # fn process<T>(_: T) -> Box<Future<Item = (), Error = ()> + Send> { //! # unimplemented!(); //! # } //! # fn dox() { //! # let addr = "127.0.0.1:8080".parse().unwrap(); //! let listener = TcpListener::bind(&addr).unwrap(); //! //! let server = listener.incoming() //! .map_err(|e| println!("error = {:?}", e)) //! .for_each(|socket| { //! tokio::spawn(process(socket)) //! }); //! //! // Create the runtime //! let mut rt = Runtime::new().unwrap(); //! //! // Spawn the server task //! rt.spawn(server); //! //! // Wait until the runtime becomes idle and shut it down. //! rt.shutdown_on_idle() //! .wait().unwrap(); //! # } //! # pub fn main() {} //! ``` //! //! [reactor]: ../reactor/struct.Reactor.html //! [executor]: https://tokio.rs/docs/getting-started/runtime-model/#executors //! [timer]: ../timer/index.html //! [`Runtime`]: struct.Runtime.html //! [`Reactor`]: ../reactor/struct.Reactor.html //! [`ThreadPool`]: https://docs.rs/tokio-threadpool/0.1/tokio_threadpool/struct.ThreadPool.html //! [`run`]: fn.run.html //! [idle]: struct.Runtime.html#method.shutdown_on_idle //! [`tokio::spawn`]: ../executor/fn.spawn.html //! [`Timer`]: https://docs.rs/tokio-timer/0.2/tokio_timer/timer/struct.Timer.html pub mod current_thread; mod threadpool; pub use self::threadpool::{ Builder, Runtime, Shutdown, TaskExecutor, run, };