From 02aaea28b9976e983ada38d84d4655856d4ff109 Mon Sep 17 00:00:00 2001
From: Jonas Fassbender <jonas@fc-web.de>
Date: Mon, 16 Sep 2024 21:58:24 +0200
Subject: [PATCH] sync: document runtime compatibility (#6833)
---
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
//!