Repository: tokio-rs/tokio
File: tokio/src/sync/mod.rs (Rust)

Code before:
//!
//! * [`Notify`] Basic task notification. `Notify` supports notifying a
//!   receiving task without sending data. In this case, the task wakes up and
//!   resumes processing.
//!
//! * [`RwLock`] Provides a mutual exclusion mechanism which allows multiple
//!   readers at the same time, while allowing only one writer at a time. In
//!   some cases, this can be more efficient than a mutex.
//!
//! * [`Semaphore`] Limits the amount of concurrency. A semaphore holds a
//!   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),
//! periodically yielding back control to the runtime to avoid starving it.
//! In a non-Tokio runtime, the yield points where control is handed back do
//! nothing, not changing the behavior of the synchronization primitive in any
//! way.
//!
//! The only exception to runtime compatibility is the
//! [`mpsc::Sender::send_timeout`] method, which can't be called from non-Tokio
//! runtimes. However, [`Senders`](mpsc::Sender) can still be moved between
//! different instances of the Tokio runtime.

cfg_sync! {
    /// Named future types.
    pub mod futures {
        pub use super::notify::Notified;
    }

    mod barrier;
    pub use barrier::{Barrier, BarrierWaitResult};

    pub mod broadcast;

    pub mod mpsc;

    mod mutex;
    pub use mutex::{Mutex, MutexGuard, TryLockError, OwnedMutexGuard, MappedMutexGuard, OwnedMappedMutexGuard};

    pub(crate) mod notify;
    pub use notify::Notify;


Review comment (suggestion):
The current wording talks a lot about how cooperative scheduling works internally, but we should not assume that the reader knows how coop works.
```suggestion
//! 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.
```

Code after:
//!
//! * [`Notify`] Basic task notification. `Notify` supports notifying a
//!   receiving task without sending data. In this case, the task wakes up and
//!   resumes processing.
//!
//! * [`RwLock`] Provides a mutual exclusion mechanism which allows multiple
//!   readers at the same time, while allowing only one writer at a time. In
//!   some cases, this can be more efficient than a mutex.
//!
//! * [`Semaphore`] Limits the amount of concurrency. A semaphore holds a
//!   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.
    pub mod futures {
        pub use super::notify::Notified;
    }

    mod barrier;
    pub use barrier::{Barrier, BarrierWaitResult};

    pub mod broadcast;

    pub mod mpsc;

    mod mutex;
    pub use mutex::{Mutex, MutexGuard, TryLockError, OwnedMutexGuard, MappedMutexGuard, OwnedMappedMutexGuard};

    pub(crate) mod notify;
    pub use notify::Notify;

    pub mod oneshot;

    pub(crate) mod batch_semaphore;
    pub use batch_semaphore::{AcquireError, TryAcquireError};