From a8d456b6e7ff0bfe74780b8e032a4eb6bf4b3164 Mon Sep 17 00:00:00 2001 From: Theodore Dubois Date: Tue, 3 Sep 2024 21:09:51 -0700 Subject: [PATCH] Unbury the lede on tokio::sync::mutex docs Fixes #5024 --- tokio/src/sync/mutex.rs | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/tokio/src/sync/mutex.rs b/tokio/src/sync/mutex.rs index 30f0bdecedb..89bfcd63b66 100644 --- a/tokio/src/sync/mutex.rs +++ b/tokio/src/sync/mutex.rs @@ -23,8 +23,11 @@ use std::{fmt, mem, ptr}; /// /// # Which kind of mutex should you use? /// -/// Contrary to popular belief, it is ok and often preferred to use the ordinary -/// [`Mutex`][std] from the standard library in asynchronous code. +/// The ordinary std [`Mutex`][std] cannot be held across an `.await` point - +/// your program will deadlock if you do this. Use the async mutex instead in +/// such cases. However, it is ok and often preferred to use the std mutex in +/// asynchronous tasks when it does not need to be held across an `.await` +/// point. /// /// The feature that the async mutex offers over the blocking mutex is the /// ability to keep it locked across an `.await` point. This makes the async