tokio-macros: add docs for flavor = "local"

Author: Twey

tokio-macros/src/lib.rs

@@ -46,7 +46,12 @@ use proc_macro::TokenStream;
 /// Awaiting on other futures from the function provided here will not
 /// perform as fast as those spawned as workers.
 ///
-/// # Multi-threaded runtime
+/// # Runtime flavors
+///
+/// The macro can be configured with a `flavor` parameter to select
+/// different runtime configurations.
+///
+/// ## Multi-threaded
 ///
 /// To use the multi-threaded runtime, the macro can be configured using
 ///
@@ -61,7 +66,7 @@ use proc_macro::TokenStream;
 /// Note: The multi-threaded runtime requires the `rt-multi-thread` feature
 /// flag.
 ///
-/// # Current thread runtime
+/// ## Current-thread
 ///
 /// To use the single-threaded runtime known as the `current_thread` runtime,
 /// the macro can be configured using
@@ -71,13 +76,13 @@ use proc_macro::TokenStream;
 /// # async fn main() {}
 /// ```
 ///
-/// ## Function arguments:
+/// # Function arguments
 ///
-/// Arguments are allowed for any functions aside from `main` which is special
+/// Arguments are allowed for any functions, aside from `main` which is special.
 ///
-/// ## Usage
+/// # Usage
 ///
-/// ### Using the multi-thread runtime
+/// ## Using the multi-threaded runtime
 ///
 /// ```rust
 /// #[tokio::main]
@@ -100,7 +105,7 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Using current thread runtime
+/// ## Using the current-thread runtime
 ///
 /// The basic scheduler is single-threaded.
 ///
@@ -125,7 +130,37 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Set number of worker threads
+/// ## Using the local runtime
+///
+/// Available with [`tokio_unstable`](../tokio#unstable-features) only.
+///
+/// The [local runtime](../tokio/runtime/struct.LocalRuntime.html) is
+/// similar to the current-thread runtime but supports
+/// [`task::spawn_local`](../tokio/task/fn.spawn_local.html).
+///
+/// ```rust
+/// #[tokio::main(flavor = "local")]
+/// async fn main() {
+///     println!("Hello world");
+/// }
+/// ```
+///
+/// Equivalent code not using `#[tokio::main]`
+///
+/// ```rust
+/// fn main() {
+///     tokio::runtime::Builder::new_current_thread()
+///         .enable_all()
+///         .build_local(tokio::runtime::LocalOptions::default())
+///         .unwrap()
+///         .block_on(async {
+///             println!("Hello world");
+///         })
+/// }
+/// ```
+///
+///
+/// ## Set number of worker threads
 ///
 /// ```rust
 /// #[tokio::main(worker_threads = 2)]
@@ -149,7 +184,7 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Configure the runtime to start with time paused
+/// ## Configure the runtime to start with time paused
 ///
 /// ```rust
 /// #[tokio::main(flavor = "current_thread", start_paused = true)]
@@ -175,7 +210,7 @@ use proc_macro::TokenStream;
 ///
 /// Note that `start_paused` requires the `test-util` feature to be enabled.
 ///
-/// ### Rename package
+/// ## Rename package
 ///
 /// ```rust
 /// use tokio as tokio1;
@@ -202,7 +237,7 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Configure unhandled panic behavior
+/// ## Configure unhandled panic behavior
 ///
 /// Available options are `shutdown_runtime` and `ignore`. For more details, see
 /// [`Builder::unhandled_panic`].