From 09887f16c83b268e6ba067d80c847c6d189fb60a Mon Sep 17 00:00:00 2001 From: Jonathan Grynspan Date: Thu, 13 Nov 2025 14:04:44 -0500 Subject: [PATCH] Adjust the docs for `Mutex.withLockIfAvailable()` re: spurious failures. This PR adjusts the documentation for `Mutex.withLockIfAvailable()` to clarify that it is not subject to spurious failures. The C11 and C++11 specs for their respective `tryLock()` APIs allow for spurious failures, but our implementations and those of every other similar API I've found don't use weak `cmpxchg`s and don't spuriously fail. --- stdlib/public/Synchronization/Mutex/Mutex.swift | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/stdlib/public/Synchronization/Mutex/Mutex.swift b/stdlib/public/Synchronization/Mutex/Mutex.swift index bc7dc2a5a14e9..88c0b5f652bdb 100644 --- a/stdlib/public/Synchronization/Mutex/Mutex.swift +++ b/stdlib/public/Synchronization/Mutex/Mutex.swift @@ -120,8 +120,13 @@ extension Mutex where Value: ~Copyable { /// as it will only be executed if the calling thread acquires /// the lock. /// - /// - Returns: The return value, if any, of the `body` closure parameter - /// or nil if the lock couldn't be acquired. + /// - Returns: The return value, if any, of the `body` closure parameter or + /// `nil` if the lock couldn’t be acquired. + /// + /// - Note: This function cannot spuriously fail to acquire the lock. The + /// behavior of similar functions in other languages (such as C's + /// `mtx_trylock()`) is platform-dependent and may differ from Swift's + /// behavior. @available(SwiftStdlib 6.0, *) @_alwaysEmitIntoClient @_transparent