summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorLucio Franco <luciofranco14@gmail.com>2020-10-13 18:49:19 -0400
committerGitHub <noreply@github.com>2020-10-13 15:49:19 -0700
commit30b40ef518d1767736c8ff47c794481e88bfd3e9 (patch)
tree4c7dab704c504dcc3395698a2749fbcbc55026d4
parent22fa88329645e7e819601d3dac8f0afafbca824f (diff)
rt: update docs for `0.3` changes (#2956)
This PR updates the runtime module docs to the changes made in `0.3` release of tokio. Closes #2720
-rw-r--r--tokio/src/runtime/builder.rs15
-rw-r--r--tokio/src/runtime/mod.rs78
2 files changed, 55 insertions, 38 deletions
diff --git a/tokio/src/runtime/builder.rs b/tokio/src/runtime/builder.rs
index bc0b29b9..e9ed3820 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 7ce3881c..d7958d60 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<dyn std::error::Error>> {
-//! 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<dyn std::error::Error>> {
+//! 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
@@ -290,17 +300,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.
@@ -324,6 +328,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<Runtime> {
Builder::new_multi_thread().enable_all().build()
}
@@ -373,19 +378,24 @@ 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 asynchronous execution context.
+ /// This function panics if the provided future panics, or if not called within an
+ /// asynchronous execution context.
///
/// # Examples
///