Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

locking/mutex: Clarify that mutex_unlock(), and most other sleeping locks, can still use the lock object after it's unlocked

Clarify the mutex lock lifetime rules a bit more.

Signed-off-by: Ingo Molnar <mingo@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Jann Horn <jannh@google.com>
Cc: Linus Torvalds <torvalds@linux-foundation.org>
Link: https://lore.kernel.org/r/20231201121808.GL3818@noisy.programming.kicks-ass.net

+18 -6
+18 -6
Documentation/locking/mutex-design.rst
··· 101 101 - Detects multi-task circular deadlocks and prints out all affected 102 102 locks and tasks (and only those tasks). 103 103 104 - Releasing a mutex is not an atomic operation: Once a mutex release operation 105 - has begun, another context may be able to acquire the mutex before the release 106 - operation has fully completed. The mutex user must ensure that the mutex is not 107 - destroyed while a release operation is still in progress - in other words, 108 - callers of mutex_unlock() must ensure that the mutex stays alive until 109 - mutex_unlock() has returned. 104 + Mutexes - and most other sleeping locks like rwsems - do not provide an 105 + implicit reference for the memory they occupy, which reference is released 106 + with mutex_unlock(). 107 + 108 + [ This is in contrast with spin_unlock() [or completion_done()], which 109 + APIs can be used to guarantee that the memory is not touched by the 110 + lock implementation after spin_unlock()/completion_done() releases 111 + the lock. ] 112 + 113 + mutex_unlock() may access the mutex structure even after it has internally 114 + released the lock already - so it's not safe for another context to 115 + acquire the mutex and assume that the mutex_unlock() context is not using 116 + the structure anymore. 117 + 118 + The mutex user must ensure that the mutex is not destroyed while a 119 + release operation is still in progress - in other words, callers of 120 + mutex_unlock() must ensure that the mutex stays alive until mutex_unlock() 121 + has returned. 110 122 111 123 Interfaces 112 124 ----------