From 8011947f717f2c6da3f411241f92eedbfd95af7b Mon Sep 17 00:00:00 2001 From: John Nunley Date: Sat, 23 Sep 2023 10:44:56 -0700 Subject: [PATCH 1/8] Add a note comparing against std types Signed-off-by: John Nunley --- src/lib.rs | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index 244d421..045d5f1 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,6 +6,26 @@ //! * [`Mutex`] - a mutual exclusion lock. //! * [`RwLock`] - a reader-writer lock, allowing any number of readers or a single writer. //! * [`Semaphore`] - limits the number of concurrent operations. +//! +//! ## Relationship with `std::sync` +//! +//! In general, you should prefer to use [`std::sync`] types over types from this crate. +//! +//! There are two primary use cases for types from this crate: +//! +//! - You need to use a synchronization primitive in a `no_std` environment. +//! - You need to hold a lock across an `.await` point. +//! +//! If you already use `libstd` and you aren't holding locks across await points, you should use +//! [`std::sync`] instead of this crate. These types are optimized for operating system use cases, +//! are less complex and are generally much faster. In contrast, `async-lock` will actually just +//! use `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a +//! significantly slower strategy if it is not. So, there are no cases where `async-lock` is a +//! win for performance over [`std::sync`]. +//! +//! In short, you should prefer using [`std::sync`] over any of the types in this module. +//! +//! [`std::sync`]: https://doc.rust-lang.org/std/sync/index.html #![cfg_attr(not(feature = "std"), no_std)] #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)] From 5f55f4efa3ce21e1e6d55f6cae97b7cd99ff9b3b Mon Sep 17 00:00:00 2001 From: John Nunley Date: Sun, 24 Sep 2023 00:29:12 -0700 Subject: [PATCH 2/8] Clarify notification mechanism Signed-off-by: John Nunley --- src/lib.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 045d5f1..018b6af 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,9 +18,9 @@ //! //! If you already use `libstd` and you aren't holding locks across await points, you should use //! [`std::sync`] instead of this crate. These types are optimized for operating system use cases, -//! are less complex and are generally much faster. In contrast, `async-lock` will actually just -//! use `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a -//! significantly slower strategy if it is not. So, there are no cases where `async-lock` is a +//! are less complex and are generally much faster. In contrast, `async-lock`'s notification system +//! uses `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a +//! significantly slower strategy if it is not. So, there are few cases where `async-lock` is a //! win for performance over [`std::sync`]. //! //! In short, you should prefer using [`std::sync`] over any of the types in this module. From 56faaa334c8aea17f6d0b0c2b05391d4626a5581 Mon Sep 17 00:00:00 2001 From: John Nunley Date: Sun, 12 Nov 2023 16:26:23 -0800 Subject: [PATCH 3/8] Update src/lib.rs Co-authored-by: Jules Bertholet --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 018b6af..314fb24 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -16,8 +16,8 @@ //! - You need to use a synchronization primitive in a `no_std` environment. //! - You need to hold a lock across an `.await` point. //! -//! If you already use `libstd` and you aren't holding locks across await points, you should use -//! [`std::sync`] instead of this crate. These types are optimized for operating system use cases, +//! If you already use `libstd` and you aren't holding locks across await points, you should consider +//! [`std::sync`] instead of this crate. Those types are optimized for operating system use cases, //! are less complex and are generally much faster. In contrast, `async-lock`'s notification system //! uses `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a //! significantly slower strategy if it is not. So, there are few cases where `async-lock` is a From 8e7485e8437e27e602e032ef85d4b2c12ca9a4ff Mon Sep 17 00:00:00 2001 From: John Nunley Date: Sun, 12 Nov 2023 16:28:06 -0800 Subject: [PATCH 4/8] Change language to be less aggressive Signed-off-by: John Nunley --- src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/lib.rs b/src/lib.rs index 314fb24..edb9ed7 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,7 +9,7 @@ //! //! ## Relationship with `std::sync` //! -//! In general, you should prefer to use [`std::sync`] types over types from this crate. +//! In general, you should consider using [`std::sync`] types over types from this crate. //! //! There are two primary use cases for types from this crate: //! From 0d50b31b504d19cf45c8cf3206fb1f67c80a42c2 Mon Sep 17 00:00:00 2001 From: John Nunley Date: Sun, 12 Nov 2023 16:46:11 -0800 Subject: [PATCH 5/8] Mention the Clippy lint Signed-off-by: John Nunley --- src/lib.rs | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index edb9ed7..a102442 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -22,10 +22,16 @@ //! uses `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a //! significantly slower strategy if it is not. So, there are few cases where `async-lock` is a //! win for performance over [`std::sync`]. +//! +//! When using [`std::sync`], you should be careful to not hold any locks over an `.await` point. +//! In modern Rust, there is a Clippy lint called [`await_holding_lock`] that emits warnings for this +//! scenario for [`std::sync`] and some other synchronization crates. Still, when deciding to use +//! [`std::sync`] over `async-lock`, you must be careful to not hold any locks past an `.await` point. //! //! In short, you should prefer using [`std::sync`] over any of the types in this module. //! //! [`std::sync`]: https://doc.rust-lang.org/std/sync/index.html +//! [`await_holding_lock`]: https://rust-lang.github.io/rust-clippy/stable/index.html#/await_holding_lock #![cfg_attr(not(feature = "std"), no_std)] #![warn(missing_docs, missing_debug_implementations, rust_2018_idioms)] From 9c908e14aba2155547b6a4e16cb962be8a0e37ef Mon Sep 17 00:00:00 2001 From: John Nunley Date: Mon, 13 Nov 2023 18:01:59 -0800 Subject: [PATCH 6/8] Update src/lib.rs Co-authored-by: Jules Bertholet --- src/lib.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/lib.rs b/src/lib.rs index a102442..d1cbb4e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -15,6 +15,8 @@ //! //! - You need to use a synchronization primitive in a `no_std` environment. //! - You need to hold a lock across an `.await` point. +//! (Holding an [`std::sync`] lock guard across an `.await` will make your future non-`Send`, +//! and is also highly likely to cause deadlocks.) //! //! If you already use `libstd` and you aren't holding locks across await points, you should consider //! [`std::sync`] instead of this crate. Those types are optimized for operating system use cases, From a1983c97bcf98517fe7cbbcfd9eff5310cef357a Mon Sep 17 00:00:00 2001 From: John Nunley Date: Mon, 13 Nov 2023 18:04:17 -0800 Subject: [PATCH 7/8] Reduce repetition in docs Signed-off-by: John Nunley --- src/lib.rs | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index d1cbb4e..fbece6c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -18,19 +18,14 @@ //! (Holding an [`std::sync`] lock guard across an `.await` will make your future non-`Send`, //! and is also highly likely to cause deadlocks.) //! -//! If you already use `libstd` and you aren't holding locks across await points, you should consider -//! [`std::sync`] instead of this crate. Those types are optimized for operating system use cases, -//! are less complex and are generally much faster. In contrast, `async-lock`'s notification system -//! uses `std::sync::Mutex` under the hood if the `std` feature is enabled, and will fall back to a -//! significantly slower strategy if it is not. So, there are few cases where `async-lock` is a -//! win for performance over [`std::sync`]. -//! -//! When using [`std::sync`], you should be careful to not hold any locks over an `.await` point. -//! In modern Rust, there is a Clippy lint called [`await_holding_lock`] that emits warnings for this -//! scenario for [`std::sync`] and some other synchronization crates. Still, when deciding to use -//! [`std::sync`] over `async-lock`, you must be careful to not hold any locks past an `.await` point. +//! If you already use `libstd` and you aren't holding locks across await points (there is a +//! Clippy lint called [`await_holding_lock`] that emits warnings for this scenario), you should +//! consider [`std::sync`] instead of this crate. Those types are optimized for operating system +//! use cases, are less complex and are generally much faster. //! -//! In short, you should prefer using [`std::sync`] over any of the types in this module. +//! In contrast, `async-lock`'s notification system uses `std::sync::Mutex` under the hood if +//! the `std` feature is enabled, and will fall back to a significantly slower strategy if it is +//! not. So, there are few cases where `async-lock` is a win for performance over [`std::sync`]. //! //! [`std::sync`]: https://doc.rust-lang.org/std/sync/index.html //! [`await_holding_lock`]: https://rust-lang.github.io/rust-clippy/stable/index.html#/await_holding_lock From cae42ad7bf05c860ac73e53df998243aa8fc95c4 Mon Sep 17 00:00:00 2001 From: John Nunley Date: Mon, 13 Nov 2023 18:34:34 -0800 Subject: [PATCH 8/8] Clarify "operating systems" comment Signed-off-by: John Nunley --- src/lib.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index fbece6c..e0aadde 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -20,8 +20,8 @@ //! //! If you already use `libstd` and you aren't holding locks across await points (there is a //! Clippy lint called [`await_holding_lock`] that emits warnings for this scenario), you should -//! consider [`std::sync`] instead of this crate. Those types are optimized for operating system -//! use cases, are less complex and are generally much faster. +//! consider [`std::sync`] instead of this crate. Those types are optimized for the currently +//! running operating system, are less complex and are generally much faster. //! //! In contrast, `async-lock`'s notification system uses `std::sync::Mutex` under the hood if //! the `std` feature is enabled, and will fall back to a significantly slower strategy if it is