Repository: tokio-rs/tokio (language: rust)

Issue:
Documenting the fact that the `sync` module is runtime agnostic
In [this](https://users.rust-lang.org/t/is-there-an-easy-way-to-have-a-channel-that-sends-in-blocking-mode-receives-in-async-mode/117183?u=jofas) URLO topic, OP is looking for a runtime agnostic channel implementation supporting both sync and async operations. I remembered reading somewhere that everything in the [`sync`](https://docs.rs/tokio/latest/tokio/sync/index.html) module is runtime agnostic.[^1] I expected this to be stated in the documentation of the `sync` module, but alas, only in the `sync::mpsc` module the docs mention that the channel is [runtime agnostic](https://docs.rs/tokio/latest/tokio/sync/mpsc/index.html#multiple-runtimes).

In response to the above-mentioned URLO topic and #4232, I was wondering if the docs could be improved to make it clearer that everything in `sync` is runtime agnostic, not just the `mpsc` channel. For me a small section in the docs of the `sync` module would've been sufficient, but of course, this is just a suggestion and there might be better ways to document what parts of Tokio [are runtime agnostic](https://github.com/tokio-rs/tokio/issues/4232#issuecomment-968329443) and what parts aren't.

FYI I'd be interested in whipping up a PR if this is a desired fix and there is consensus on what should be documented and where to put it.

[^1]:  Barring one [exception](https://docs.rs/tokio/latest/tokio/sync/mpsc/struct.Sender.html#method.send_timeout).


Discussion / hints:
I think it would be great to have a section in the sync module docs about runtime compatibility. 

Fix patch:
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
 //!


Test patch: