runtime: add guide for choosing between runtime types (#7635)

Signed-off-by: ADD-SP <qiqi.zhang@konghq.com>

diff --git a/spellcheck.dic b/spellcheck.dic
index 3182d65ad444b14c6539593b6ad7fc080ad50ad7..2baf2df351f0f96c34c43bf608f023dc4fabe86a 100644 (file)
--- a/spellcheck.dic
+++ b/spellcheck.dic
@@ -1,4 +1,4 @@
-307
+308
 &
 +
 <
@@ -190,6 +190,7 @@ nonblocking
 nondecreasing
 noop
 ntasks
+NUMA
 ok
 oneshot
 ORed

diff --git a/tokio/src/runtime/mod.rs b/tokio/src/runtime/mod.rs
index a70e76aa29cd2aa06f25304c6009de0a4690248c..ae58ce6da86c29d8f612ae5d913a2fdc067566a5 100644 (file)
--- a/tokio/src/runtime/mod.rs
+++ b/tokio/src/runtime/mod.rs
@@ -13,6 +13,52 @@
 //! not required to configure a [`Runtime`] manually, and a user may just use the
 //! [`tokio::main`] attribute macro, which creates a [`Runtime`] under the hood.
 //!
+//! # Choose your runtime
+//!
+//! Here is the rules of thumb to choose the right runtime for your application.
+//!
+//! ```plaintext
+//!    +------------------------------------------------------+
+//!    | Do you want work-stealing or multi-thread scheduler? |
+//!    +------------------------------------------------------+
+//!                    | Yes              | No
+//!                    |                  |
+//!                    |                  |
+//!                    v                  |
+//!      +------------------------+       |
+//!      | Multi-threaded Runtime |       |
+//!      +------------------------+       |
+//!                                       |
+//!                                       V
+//!                      +--------------------------------+
+//!                      | Do you execute `!Send` Future? |
+//!                      +--------------------------------+
+//!                            | Yes                 | No
+//!                            |                     |
+//!                            V                     |
+//!              +--------------------------+        |
+//!              | Local Runtime (unstable) |        |
+//!              +--------------------------+        |
+//!                                                  |
+//!                                                  v
+//!                                      +------------------------+
+//!                                      | Current-thread Runtime |
+//!                                      +------------------------+
+//! ```
+//!
+//! The above decision tree is not exhaustive. there are other factors that
+//! may influence your decision.
+//!
+//! ## Bridging with sync code
+//!
+//! See <https://tokio.rs/tokio/topics/bridging> for details.
+//!
+//! ## NUMA awareness
+//!
+//! The tokio runtime is not NUMA (Non-Uniform Memory Access) aware.
+//! You may want to start multiple runtimes instead of a single runtime
+//! for better performance on NUMA systems.
+//!
 //! # Usage
 //!
 //! When no fine tuning is required, the [`tokio::main`] attribute macro can be