From db5dfd2373fb6774bf7d95f3dbab0818415f421b Mon Sep 17 00:00:00 2001 From: The 8472 Date: Tue, 14 Mar 2023 21:57:26 +0100 Subject: [PATCH 1/2] Add block-based mutex unlocking example --- library/std/src/sync/mutex.rs | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/library/std/src/sync/mutex.rs b/library/std/src/sync/mutex.rs index 065045f442069..2f7c609c83ef0 100644 --- a/library/std/src/sync/mutex.rs +++ b/library/std/src/sync/mutex.rs @@ -107,8 +107,8 @@ use crate::sys::locks as sys; /// *guard += 1; /// ``` /// -/// It is sometimes necessary to manually drop the mutex guard to unlock it -/// sooner than the end of the enclosing scope. +/// It is sometimes necessary to manually drop the mutex guard or to create an inner scope +/// to unlock it sooner than the end of the enclosing scope. /// /// ``` /// use std::sync::{Arc, Mutex}; @@ -125,11 +125,18 @@ use crate::sys::locks as sys; /// let res_mutex_clone = Arc::clone(&res_mutex); /// /// threads.push(thread::spawn(move || { -/// let mut data = data_mutex_clone.lock().unwrap(); -/// // This is the result of some important and long-ish work. -/// let result = data.iter().fold(0, |acc, x| acc + x * 2); -/// data.push(result); -/// drop(data); +/// // Here we use a block to limit the lifetime of the lock guard. +/// let result = { +/// let mut data = data_mutex_clone.lock().unwrap(); +/// // This is the result of some important and long-ish work. +/// let result = data.iter().fold(0, |acc, x| acc + x * 2); +/// data.push(result); +/// result +/// // The mutex guard gets dropped here, together with any other values +/// // created in the critical section. +/// }; +/// // The guard created here is a temporary dropped at the end of the statement, i.e. +/// // the lock would not remain being held even if the thread did some additional work. /// *res_mutex_clone.lock().unwrap() += result; /// })); /// }); @@ -146,6 +153,8 @@ use crate::sys::locks as sys; /// // It's even more important here than in the threads because we `.join` the /// // threads after that. If we had not dropped the mutex guard, a thread could /// // be waiting forever for it, causing a deadlock. +/// // As in the threads a block could have been used instead of calling the +/// // `drop` function. /// drop(data); /// // Here the mutex guard is not assigned to a variable and so, even if the /// // scope does not end after this line, the mutex is still released: there is @@ -160,6 +169,7 @@ use crate::sys::locks as sys; /// /// assert_eq!(*res_mutex.lock().unwrap(), 800); /// ``` +/// #[stable(feature = "rust1", since = "1.0.0")] #[cfg_attr(not(test), rustc_diagnostic_item = "Mutex")] pub struct Mutex { From a3e41b57593cb58729f0761e0cf9f25db5639af6 Mon Sep 17 00:00:00 2001 From: the8472 Date: Mon, 20 Mar 2023 12:07:27 +0100 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Josh Stone --- library/std/src/sync/mutex.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/std/src/sync/mutex.rs b/library/std/src/sync/mutex.rs index 2f7c609c83ef0..b8fec6902a08c 100644 --- a/library/std/src/sync/mutex.rs +++ b/library/std/src/sync/mutex.rs @@ -107,8 +107,8 @@ use crate::sys::locks as sys; /// *guard += 1; /// ``` /// -/// It is sometimes necessary to manually drop the mutex guard or to create an inner scope -/// to unlock it sooner than the end of the enclosing scope. +/// To unlock a mutex guard sooner than the end of the enclosing scope, +/// either create an inner scope or drop the guard manually. /// /// ``` /// use std::sync::{Arc, Mutex}; @@ -153,7 +153,7 @@ use crate::sys::locks as sys; /// // It's even more important here than in the threads because we `.join` the /// // threads after that. If we had not dropped the mutex guard, a thread could /// // be waiting forever for it, causing a deadlock. -/// // As in the threads a block could have been used instead of calling the +/// // As in the threads, a block could have been used instead of calling the /// // `drop` function. /// drop(data); /// // Here the mutex guard is not assigned to a variable and so, even if the