From 4ea7da6cfae63996f4f5e1c5c8cf14c0ef5e711e Mon Sep 17 00:00:00 2001 From: jofas Date: Tue, 10 Sep 2024 08:38:19 +0200 Subject: [PATCH] Doc section for sync module on runtime compatibility --- tokio/src/sync/mod.rs | 14 ++++++++++++++ tokio/src/sync/mpsc/mod.rs | 16 ++++++++++------ 2 files changed, 24 insertions(+), 6 deletions(-) diff --git a/tokio/src/sync/mod.rs b/tokio/src/sync/mod.rs index ef7a09a89b6..ddf99644270 100644 --- a/tokio/src/sync/mod.rs +++ b/tokio/src/sync/mod.rs @@ -431,6 +431,20 @@ //! number of permits, which tasks may request in order to enter a critical //! section. Semaphores are useful for implementing limiting or bounding of //! any kind. +//! +//! # Runtime compatibility +//! +//! All synchronization primitives provided in this module are runtime agnostic. +//! You can freely move them between different instances of the Tokio runtime +//! or even use them from non-Tokio runtimes. +//! +//! When used in a Tokio runtime, the synchronization primitives participate in +//! [cooperative scheduling](crate::task#cooperative-scheduling) to avoid +//! starvation. This feature does not apply when used from non-Tokio runtimes. +//! +//! As an exception, methods ending in `_timeout` are not runtime agnostic +//! because they require access to the Tokio timer. See the documentation of +//! each `*_timeout` method for more information on its use. cfg_sync! { /// Named future types. diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs index e6601e90a4a..a90a35d366b 100644 --- a/tokio/src/sync/mpsc/mod.rs +++ b/tokio/src/sync/mpsc/mod.rs @@ -70,13 +70,17 @@ //! //! # Multiple runtimes //! -//! The mpsc channel does not care about which runtime you use it in, and can be -//! used to send messages from one runtime to another. It can also be used in -//! non-Tokio runtimes. +//! The `mpsc` channel is runtime agnostic. You can freely move it between +//! different instances of the Tokio runtime or even use it from non-Tokio +//! runtimes. //! -//! There is one exception to the above: the [`send_timeout`] must be used from -//! within a Tokio runtime, however it is still not tied to one specific Tokio -//! runtime, and the sender may be moved from one Tokio runtime to another. +//! When used in a Tokio runtime, it participates in +//! [cooperative scheduling](crate::task#cooperative-scheduling) to avoid +//! starvation. This feature does not apply when used from non-Tokio runtimes. +//! +//! As an exception, methods ending in `_timeout` are not runtime agnostic +//! because they require access to the Tokio timer. See the documentation of +//! each `*_timeout` method for more information on its use. //! //! # Allocation behavior //!