From 6866fe426cfab0e4da3e88c673f7bef141259bb6 Mon Sep 17 00:00:00 2001 From: Eliza Weisman Date: Thu, 21 Nov 2019 14:09:10 -0800 Subject: [PATCH] docs: expand and update crate-level docs (#1806) ## Motivation Tokio's crate-level docs are currently pretty sparse, and in some cases reference old names for APIs. Before 0.2 is released, they could use a fresh coat of paint. ## Solution This branch reworks and expands the `lib.rs` docs. In particular, I've added a new "A Tour of Tokio" section, inspired by the [standard library's similarly-named section][std]. This section lists all of `tokio`'s public modules, and summarizes their major APIs. It also lists the feature flags necessary to enable those APIs. [std]: https://doc.rust-lang.org/std/index.html#a-tour-of-the-rust-standard-library Signed-off-by: Eliza Weisman --- tokio/src/lib.rs | 148 ++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 141 insertions(+), 7 deletions(-) diff --git a/tokio/src/lib.rs b/tokio/src/lib.rs index aa08aeeb3..88290f98a 100644 --- a/tokio/src/lib.rs +++ b/tokio/src/lib.rs @@ -17,18 +17,152 @@ //! applications with the Rust programming language. At a high level, it //! provides a few major components: //! -//! * A multi threaded, work-stealing based task [scheduler][runtime]. -//! * A [driver] backed by the operating system's event queue (epoll, kqueue, -//! IOCP, etc...). -//! * Asynchronous [TCP and UDP][net] sockets. -//! * Asynchronous [filesystem][fs] operations. -//! * [Timer][time] API for scheduling work in the future. +//! * Tools for [working with asynchronous tasks][tasks], including +//! [synchronization primitives and channels][sync] and [timeouts, delays, and +//! intervals][time]. +//! * APIs for [performing asynchronous I/O][io], including [TCP and UDP][net] sockets, +//! [filesystem][fs] operations, and [process] and [signal] management. +//! * A [runtime] for executing asynchronous code, including a task scheduler, +//! an I/O driver backed by the operating system's event queue (epoll, kqueue, +//! IOCP, etc...), and a high performance timer. //! //! Guide level documentation is found on the [website]. //! -//! [driver]: driver/index.html +//! [tasks]: #working-with-tasks +//! [sync]: crate::sync +//! [time]: crate::time +//! [io]: #asynchronous-io +//! [net]: crate::net +//! [fs]: crate::fs +//! [process]: crate::process +//! [signal]: crate::signal +//! [fs]: crate::fs +//! [runtime]: crate::runtime //! [website]: https://tokio.rs/docs/ //! +//! # A Tour of Tokio +//! +//! Tokio consists of a number of modules that provide a range of functionality +//! essential for implementing asynchronous applications in Rust. In this +//! 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. +//! +//! [features]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section +//! +//! ## Working With Tasks +//! +//! Asynchronous programs in Rust are based around lightweight, non-blocking +//! units of execution called [_tasks_][tasks]. The [`tokio::task`] module provides +//! important tools for working with tasks: +//! +//! * The [`spawn`] function and [`JoinHandle`] type, for scheduling a new task +//! on the Tokio runtime and awaiting the output of a spawned task, respectively, +//! * Functions for [running blocking operations][blocking] in an asynchronous +//! task context. +//! +//! The `tokio::task` module is present only when the "rt-core" feature flag is +//! enabled. +//! +//! [tasks]: task/index.html#what-are-tasks +//! [`tokio::task`]: crate::task +//! [`spawn`]: crate::task::spawn() +//! [`JoinHandle`]: crate::task::JoinHandle +//! [`blocking`]: task/index.html#blocking-and-yielding +//! +//! The [`tokio::sync`] module contains synchronization primitives to use when +//! need to communicate or share data. These include: +//! +//! * channels ([`oneshot`], [`mpsc`], and [`watch`]), for sending values +//! between tasks, +//! * a non-blocking [`Mutex`], for controlling access to a shared, mutable +//! value, +//! * an asynchronous [`Barrier`] type, for multiple tasks to synchronize before +//! beginning a computation. +//! +//! The `tokio::sync` module is present only when the "sync" feature flag is +//! enabled. +//! +//! [`tokio::sync`]: crate::sync +//! [`Mutex`]: crate::sync::Mutex +//! [`Barrier`]: crate::sync::Barrier +//! [`oneshot`]: crate::sync::oneshot +//! [`mpsc`]: crate::sync::mpsc +//! [`watch`]: crate::sync::watch +//! +//! The [`tokio::time`] module provides utilities for tracking time and +//! scheduling work. This includes functions for setting [timeouts][timeout] for +//! tasks, [delaying][delay] work to run in the future, or [repeating an operation at an +//! interval][interval]. +//! +//! In order to use `tokio::time`, the "time" feature flag must be enabled. +//! +//! [`tokio::time`]: crate::time +//! [delay]: crate::time::delay_for() +//! [interval]: crate::time::interval() +//! [timeout]: crate::time::timeout() +//! +//! Finally, Tokio provides a _runtime_ for executing asynchronous tasks. Most +//! applications can use the [`#[tokio::main]`][main] macro to run their code on the +//! Tokio runtime. In use-cases where manual control over the runtime is +//! required, the [`tokio::runtime`] module provides APIs for configuring and +//! managing runtimes. +//! +//! Using the runtime requires the "rt-core" or "rt-threaded" feature flags, to +//! enable the basic [single-threaded scheduler][rt-core] and the [thread-pool +//! scheduler][rt-threaded], respectively. See the [`runtime` module +//! documentation][rt-features] for details. In addition, the "macros" feature +//! flag enables the `#[tokio::main]` and `#[tokio::test]` attributes. +//! +//! [main]: attr.main.html +//! [`tokio::runtime`]: crate::runtime +//! [`Builder`]: crate::runtime::Builder +//! [`Runtime`]: crate::runtime::Runtime +//! [rt-core]: runtime/index.html#basic-scheduler +//! [rt-threaded]: runtime/index.html#threaded-scheduler +//! [rt-features]: runtime/index.html#runtime-scheduler +//! +//! ## Asynchronous IO +//! +//! As well as scheduling and running tasks, Tokio provides everything you need +//! to perform input and output asynchronously. +//! +//! The [`tokio::io`] module provides Tokio's asynchronous core I/O primitives, +//! the [`AsyncRead`], [`AsyncWrite`], and [`AsyncBufRead`] traits. In addition, +//! when the "io-util" feature flag is enabled, it also provides combinators and +//! functions for working with these traits, forming as an asynchronous +//! counterpart to [`std::io`]. When the "io-driver" feature flag is enabled, it +//! also provides utilities for library authors implementing I/O resources. +//! +//! Tokio also includes APIs for performing various kinds of I/O and interacting +//! with the operating system asynchronously. These include: +//! +//! * [`tokio::net`], which contains non-blocking versions of [TCP], [UDP], and +//! [Unix Domain Sockets][UDS] (enabled by the "net" feature flag), +//! * [`tokio::fs`], similar to [`std::fs`] but for performing filesystem I/O +//! asynchronously (enabled by the "fs" feature flag), +//! * [`tokio::signal`], for asynchronously handling Unix and Windows OS signals +//! (enabled by the "signal" feature flag), +//! * [`tokio::process`], for spawning and managing child processes (enabled by +//! the "process" feature flag). +//! +//! [`tokio::io`]: crate::io +//! [`AsyncRead`]: crate::io::AsyncRead +//! [`AsyncWrite`]: crate::io::AsyncWrite +//! [`AsyncBufRead`]: crate::io::AsyncBufRead +//! [`std::io`]: std::io +//! [`tokio::net`]: crate::net +//! [TCP]: crate::net::tcp +//! [UDP]: crate::net::udp +//! [UDS]: crate::net::unix +//! [`tokio::fs`]: crate::fs +//! [`std::fs`]: std::fs +//! [`tokio::signal`]: crate::signal +//! [`tokio::process`]: crate::process +//! //! # Examples //! //! A simple TCP echo server: