diff options
Diffstat (limited to 'tokio/src/lib.rs')
-rw-r--r-- | tokio/src/lib.rs | 75 |
1 files changed, 70 insertions, 5 deletions
diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index b8f1421c..7355ab70 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -49,10 +49,6 @@ //! section, we will take a brief tour of Tokio, summarizing the major APIs and //! their uses. //! -//! Note that Tokio uses [Cargo feature flags][features] to allow users to -//! control what features are present, so that unused code can be eliminated. -//! This documentation also lists what feature flags are necessary to enable each API. -//! //! The easiest way to get started is to enable all features. Do this by //! enabling the `full` feature flag: //! @@ -60,7 +56,76 @@ //! tokio = { version = "0.2", features = ["full"] } //! ``` //! -//! [features]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +//! ## Feature flags +//! +//! Tokio uses a set of [feature flags] to reduce the amount of compiled code. It +//! is possible to just enable certain features over others. By default, Tokio +//! does not enable any features but allows one to enable a subset for their use +//! case. Below is a list of the available feature flags. You may also notice +//! above each function, struct and trait there is a set of feature flags +//! that are required for that item to be enabled. If you are new to Tokio it is +//! recommended that you use the `full` feature flag which will enable everything. +//! Beware though that this will pull in many extra dependencies that you may not +//! need. +//! +//! - `full`: Enables all Tokio features and every API will be available. +//! - `rt-core`: Enables `tokio::spawn` and the basic (single-threaded) scheduler. +//! - `rt-threaded`: Enables the heavier, multi-threaded, work-stealing scheduler. +//! - `rt-util`: Enables non-scheduler utilities. +//! - `io-driver`: Enables the `mio` based IO driver. +//! - `io-util`: Enables the IO based `Ext` traits. +//! - `io-std`: Enable `Stdout`, `Stdin` and `Stderr` types. +//! - `net`: Enables `tokio::net` types such as `TcpStream`, `UnixStream` and `UdpSocket`. +//! - `tcp`: Enables all `tokio::net::tcp` types. +//! - `udp`: Enables all `tokio::net::udp` types. +//! - `uds`: Enables all `tokio::net::unix` types. +//! - `time`: Enables `tokio::time` types and allows the schedulers to enable +//! the built in timer. +//! - `process`: Enables `tokio::process` types. +//! - `macros`: Enables `#[tokio::main]` and `#[tokio::test]` macros. +//! - `sync`: Enables all `tokio::sync` types. +//! - `stream`: Enables optional `Stream` implementations for types within Tokio. +//! - `signal`: Enables all `tokio::signal` types. +//! - `fs`: Enables `tokio::fs` types. +//! - `dns`: Enables async `tokio::net::ToSocketAddrs`. +//! - `test-util`: Enables testing based infrastructure for the Tokio runtime. +//! - `blocking`: Enables `block_in_place` and `spawn_blocking`. +//! +//! _Note: `AsyncRead` and `AsyncWrite` do not require any features and are +//! enabled by default._ +//! +//! [feature flags]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +//! +//! ### Authoring applications +//! +//! Tokio is great for writing applications and most users in this case shouldn't +//! worry to much about what features they should pick. If you're unsure, we suggest +//! going with `full` to ensure that you don't run into any road blocks while you're +//! building your application. +//! +//! #### Example +//! +//! This example shows the quickest way to get started with Tokio. +//! +//! ```toml +//! tokio = { version = "0.2", features = ["full"] } +//! ``` +//! +//! ### Authoring libraries +//! +//! As a library author your goal should be to provide the lighest weight crate +//! that is based on Tokio. To achieve this you should ensure that you only enable +//! the features you need. This allows users to pick up your crate without having +//! to enable unnecessary features. +//! +//! #### Example +//! +//! This example shows how you may want to import features for a library that just +//! needs to `tokio::spawn` and use a `TcpStream`. +//! +//! ```toml +//! tokio = { version = "0.2", features = ["rt-core", "tcp"] } +//! ``` //! //! ## Working With Tasks //! |