From b157f5da76a50063f831112f8ca7ccc787120f50 Mon Sep 17 00:00:00 2001 From: Qi Date: Wed, 1 Oct 2025 22:00:46 +0800 Subject: [PATCH] runtime: add guide for choosing between runtime types (#7635) Signed-off-by: ADD-SP --- spellcheck.dic | 3 ++- tokio/src/runtime/mod.rs | 46 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 1 deletion(-) diff --git a/spellcheck.dic b/spellcheck.dic index 3182d65ad..2baf2df35 100644 --- 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 a70e76aa2..ae58ce6da 100644 --- 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 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