From 254af6256048b850a7f6bec6bceb15dbca86975e Mon Sep 17 00:00:00 2001 From: Lucio Franco Date: Tue, 13 Oct 2020 13:51:57 -0400 Subject: [PATCH] rt: Update docs for `0.3` changes This PR updates the runtime module docs to the changes made in `0.3` release of tokio. Closes #2720 --- tokio/src/runtime/builder.rs | 15 +++++-- tokio/src/runtime/mod.rs | 76 ++++++++++++++++++++---------------- 2 files changed, 54 insertions(+), 37 deletions(-) diff --git a/tokio/src/runtime/builder.rs b/tokio/src/runtime/builder.rs index 735e9b6a975..ff578d8a43b 100644 --- a/tokio/src/runtime/builder.rs +++ b/tokio/src/runtime/builder.rs @@ -10,13 +10,15 @@ use std::time::Duration; /// Methods can be chained in order to set the configuration values. The /// Runtime is constructed by calling [`build`]. /// -/// New instances of `Builder` are obtained via [`Builder::new`]. +/// New instances of `Builder` are obtained via [`Builder::new_multi_thread`] +/// or [`Builder::new_current_thread`]. /// /// See function level documentation for details on the various configuration /// settings. /// /// [`build`]: method@Self::build -/// [`Builder::new`]: method@Self::new +/// [`Builder::new_multi_thread`]: method@Self::new_multi_thread +/// [`Builder::new_current_thread`]: method@Self::new_current_thread /// /// # Examples /// @@ -78,13 +80,18 @@ pub(crate) enum Kind { } impl Builder { - /// TODO + /// Returns a new builder with the multi thread scheduler selected. + /// + /// Configuration methods can be chained on the return value. pub fn new_current_thread() -> Builder { Builder::new(Kind::CurrentThread) } - /// TODO + /// Returns a new builder with the multi thread scheduler selected. + /// + /// Configuration methods can be chained on the return value. #[cfg(feature = "rt-multi-thread")] + #[cfg_attr(docsrs, doc(cfg(feature = "rt-multi-thread")))] pub fn new_multi_thread() -> Builder { Builder::new(Kind::MultiThread) } diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs index 7712a7f8525..f81c8297310 100644 --- a/tokio/src/runtime/mod.rs +++ b/tokio/src/runtime/mod.rs @@ -110,20 +110,6 @@ //! applications. The [runtime builder] or `#[tokio::main]` attribute may be //! used to select which scheduler to use. //! -//! #### Current-Thread Scheduler -//! -//! The current-thread scheduler provides a _single-threaded_ future executor. -//! All tasks will be created and executed on the current thread. This requires -//! the `rt` feature flag. -//! ``` -//! use tokio::runtime; -//! -//! # fn main() -> Result<(), Box> { -//! let basic_rt = runtime::Builder::new_current_thread() -//! .build()?; -//! # Ok(()) } -//! ``` -//! //! #### Multi-Thread Scheduler //! //! The multi-thread scheduler executes futures on a _thread pool_, using a @@ -142,6 +128,20 @@ //! Most applications should use the multi-thread scheduler, except in some //! niche use-cases, such as when running only a single thread is required. //! +//! #### Current-Thread Scheduler +//! +//! The current-thread scheduler provides a _single-threaded_ future executor. +//! All tasks will be created and executed on the current thread. This requires +//! the `rt-core` feature flag. +//! ``` +//! use tokio::runtime; +//! +//! # fn main() -> Result<(), Box> { +//! let basic_rt = runtime::Builder::new_current_thread() +//! .build()?; +//! # Ok(()) } +//! ``` +//! //! #### Resource drivers //! //! When configuring a runtime by hand, no resource drivers are enabled by @@ -153,8 +153,8 @@ //! ## Lifetime of spawned threads //! //! The runtime may spawn threads depending on its configuration and usage. The -//! threaded scheduler spawns threads to schedule tasks and calls to -//! `spawn_blocking` spawn threads to run blocking operations. +//! multi-thread scheduler spawns threads to schedule tasks and for `spawn_blocking` +//! calls. //! //! While the `Runtime` is active, threads may shutdown after periods of being //! idle. Once `Runtime` is dropped, all runtime threads are forcibly shutdown. @@ -246,6 +246,16 @@ cfg_rt! { /// that reactor will no longer function. Calling any method on them will /// result in an error. /// + /// # Sharing + /// + /// The Tokio runtime implements `Sync` and `Send` to allow you to wrap it + /// in a `Arc`. Most fn take `&self` to allow you to call them concurrently + /// accross multiple threads. + /// + /// Calls to `shutdown` and `shutdown_timeout` require exclusive ownership of + /// the runtime type and this can be achieved via `Arc::try_unwrap` when only + /// one strong count reference is left over. + /// /// [timer]: crate::time /// [mod]: index.html /// [`new`]: method@Self::new @@ -280,17 +290,11 @@ cfg_rt! { impl Runtime { /// Create a new runtime instance with default configuration values. /// - /// This results in a scheduler, I/O driver, and time driver being - /// initialized. The type of scheduler used depends on what feature flags - /// are enabled: if the `rt-multi-thread` feature is enabled, the [threaded - /// scheduler] is used, while if only the `rt` feature is enabled, the - /// [basic scheduler] is used instead. - /// - /// If the threaded scheduler is selected, it will not spawn - /// any worker threads until it needs to, i.e. tasks are scheduled to run. + /// This results in the multi threaded scheduler, I/O driver, and time driver being + /// initialized. /// /// Most applications will not need to call this function directly. Instead, - /// they will use the [`#[tokio::main]` attribute][main]. When more complex + /// they will use the [`#[tokio::main]` attribute][main]. When a more complex /// configuration is necessary, the [runtime builder] may be used. /// /// See [module level][mod] documentation for more details. @@ -314,6 +318,7 @@ cfg_rt! { /// [basic scheduler]: index.html#basic-scheduler /// [runtime builder]: crate::runtime::Builder #[cfg(feature = "rt-multi-thread")] + #[cfg_attr(docsrs, doc(cfg(feature = "rt-multi-thread")))] pub fn new() -> std::io::Result { Builder::new_multi_thread().enable_all().build() } @@ -363,17 +368,23 @@ cfg_rt! { /// complete, and yielding its resolved result. Any tasks or timers which /// the future spawns internally will be executed on the runtime. /// - /// When this runtime is configured with `core_threads = 0`, only the first call - /// to `block_on` will run the IO and timer drivers. Calls to other methods _before_ the first - /// `block_on` completes will just hook into the driver running on the thread - /// that first called `block_on`. This means that the driver may be passed - /// from thread to thread by the user between calls to `block_on`. + /// # Multi thread scheduler + /// + /// When the multi thread scheduler is used this will allow futures + /// to run within the io driver and timer context of the overall runtime. + /// + /// # Current thread scheduler /// - /// This method may not be called from an asynchronous context. + /// When the current thread scheduler is enabled `block_on` + /// can be called concurrently from multiple threads. The first call + /// will take ownership of the io and timer drivers. This means + /// other threads which do not own the drivers will hook into that one. + /// When the first `block_on` completes, other threads will be able to + /// "steal" the driver to allow continued execution of their futures. /// /// # Panics /// - /// This function panics if the provided future panics, or if called within an + /// This function panics if the provided future panics, or if not called within an /// asynchronous execution context. /// /// # Examples @@ -393,7 +404,6 @@ cfg_rt! { /// [handle]: fn@Handle::block_on pub fn block_on(&self, future: F) -> F::Output { self.handle.enter(|| match &self.kind { - #[cfg(feature = "rt")] Kind::CurrentThread(exec) => exec.block_on(future), #[cfg(feature = "rt-multi-thread")] Kind::ThreadPool(exec) => exec.block_on(future),