Add a note comparing against std types

src/lib.rs

@@ -6,6 +6,32 @@
 //! * [`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 consider using [`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 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.
+//!
+//! 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)]