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,24 @@ use proc_macro::TokenStream;
 /// # async fn main() {}
 /// ```
 ///
-/// ## Function arguments:
+/// ## Local
 ///
-/// Arguments are allowed for any functions aside from `main` which is special
+/// [Unstable API][unstable] only.
 ///
-/// ## Usage
+/// To use the [local runtime], the macro can be configured using
 ///
-/// ### Using the multi-thread runtime
+/// ```
+/// #[tokio::main(flavor = "local")]
+/// # async fn main() {}
+/// ```
+///
+/// # Function arguments
+///
+/// Arguments are allowed for any functions, aside from `main` which is special.
+///
+/// # Usage
+///
+/// ## Using the multi-threaded runtime
 ///
 /// ```rust
 /// #[tokio::main]
@@ -100,7 +116,7 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Using current thread runtime
+/// ## Using the current-thread runtime
 ///
 /// The basic scheduler is single-threaded.
 ///
@@ -125,7 +141,36 @@ use proc_macro::TokenStream;
 /// }
 /// ```
 ///
-/// ### Set number of worker threads
+/// ## Using the local runtime
+///
+/// Available in the [unstable API][unstable] only.
+///
+/// The [local runtime] 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 +194,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 +220,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 +247,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`].
@@ -247,6 +292,7 @@ use proc_macro::TokenStream;
 ///
 /// [`Builder::unhandled_panic`]: ../tokio/runtime/struct.Builder.html#method.unhandled_panic
 /// [unstable]: ../tokio/index.html#unstable-features
+/// [local runtime]: ../tokio/runtime/struct.LocalRuntime.html
 #[proc_macro_attribute]
 pub fn main(args: TokenStream, item: TokenStream) -> TokenStream {
     entry::main(args.into(), item.into(), true).into()