From 05f22e92774418b3f3e160e7e9c8285cf921c42e Mon Sep 17 00:00:00 2001
From: jofas <jonas@fc-web.de>
Date: Mon, 9 Sep 2024 20:07:30 +0200
Subject: [PATCH] Doc section for sync module on runtime compatibility

---
 tokio/src/sync/mod.rs      | 19 +++++++++++++++++++
 tokio/src/sync/mpsc/mod.rs | 13 ++++++-------
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/tokio/src/sync/mod.rs b/tokio/src/sync/mod.rs
index ef7a09a89b6..9e6d252a254 100644
--- a/tokio/src/sync/mod.rs
+++ b/tokio/src/sync/mod.rs
@@ -431,6 +431,25 @@
 //!   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.
+//!
+//! The only exception to this is the [`mpsc::Sender::send_timeout`] method.
+//! It relies on functionality from the [`time`](crate::time) module which
+//! does not allow you to call it from non-Tokio runtimes.
+//! However, [`Senders`](mpsc::Sender) can still be moved between different
+//! instances of the Tokio runtime without you losing the ability to call
+//! `send_timeout` on them.
+//!
+//! When used in a Tokio runtime, the synchronization primitives in this module
+//! participate in [cooperative scheduling](crate::task#cooperative-scheduling),
+//! periodically yielding back control to the runtime to avoid starving it.
+//! This is Tokio specific behavior that does not come into effect when the
+//! synchronization primitive is used in a non-Tokio runtime.
 
 cfg_sync! {
     /// Named future types.
diff --git a/tokio/src/sync/mpsc/mod.rs b/tokio/src/sync/mpsc/mod.rs
index e6601e90a4a..c992e463b8c 100644
--- a/tokio/src/sync/mpsc/mod.rs
+++ b/tokio/src/sync/mpsc/mod.rs
@@ -70,13 +70,12 @@
 //!
 //! # 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.
-//!
-//! 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.
+//! The mpsc channel is runtime agnostic and can be used to send messages
+//! between different runtimes, including non-Tokio runtimes.
+//! The only exception being [`send_timeout`], which needs to be called from
+//! a Tokio runtime.
+//! For more details see
+//! [the documentation of the `sync` module](crate::sync#runtime-compatibility).
 //!
 //! # Allocation behavior
 //!