P3832R1 and P3833R2

Signed-off-by: Ted Lyngmo <ted@lyncon.se>

Author: TedLyngmo

papers/P3832.md

@@ -2,14 +2,25 @@
 title: "Timed lock algorithms for multiple lockables"
 ---
 
-- **Document number:** P3832R0
+- **Document number:** P3832R1
 - **Date:** @DATE@
 - **Audience:** Library Evolution Working Group
 - **Project:** ISO/IEC 14882 Programming Languages — C++, ISO/IEC JTC1/SC22/WG21
 - **Reply-to:** Ted Lyngmo <ted@lyncon.se>
 
 ## Revision History
 
+### R1
+
+- Added link to reference implementation.
+
+Modifications after `2025-11_Kona:SG1-P3832R0` meeting:
+
+- Added a note that an implementation should ensure that `try_lock_until()` does not consistently return ≥ 0 in the absence of contending mutex acquisitions.
+- Clarified that no call to `try_lock_for()` or `try_lock_until()` is made while holding a lock on any argument.
+- Added `Throws` clause to `try_lock_until`.
+- Changed "the index of the last lockable for which locking failed" to "the index of the lockable for which `try_lock_until()` or `try_lock_for()` failed due to `abs_time` being reached" in Effects and Returns.
+
 ## Abstract
 
 C++11 introduced `std::lock` and `std::try_lock` (and C++17 introduced `std::scoped_lock`) to simplify deadlock-free acquisition of multiple lockables. These algorithms support *BasicLockable* and *Lockable* objects, but there is currently no facility for timed acquisition of multiple *TimedLockable* objects.
@@ -59,7 +70,7 @@ These extend the `std::lock` family of functions to timed lockables, enabling co
 
 ## 5. Proposed Wording
 
-The following changes are relative to N5008.
+The following changes are relative to N5014.
 
 In 32.6.6, Generic locking algorithms [thread.lock.algorithm], after point 5:
 
@@ -70,14 +81,11 @@ int try_lock_until(const chrono::time_point<Clock, Duration>& abs_time, Ls&... l
 
 **6** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Preconditions*: Each template parameter type in `Ls` meets the *Cpp17TimedLockable* requirements.
 
-**7** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Effects*: Attempts to obtain ownership of all arguments via repeated calls to `try_lock_until()`, `try_lock_for()`, `try_lock()` or `unlock()` on each argument. The sequence of calls does not result in deadlock, but is otherwise unspecified.
-
-- If all locks are acquired before `abs_time` has passed, returns `-1`.
-- If the time point `abs_time` is reached before all locks are acquired, releases any locks it holds and returns the index of the last lockable for which locking failed.
+**7** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Effects*: Attempts to obtain ownership of all arguments via repeated calls to `try_lock_until()`, `try_lock_for()`, `try_lock()` or `unlock()` on each argument. The sequence of calls does not result in deadlock. No call to `try_lock_for()` or `try_lock_until()` is made while holding a lock on any argument, but the sequence is otherwise unspecified. If all locks are acquired before `abs_time` has passed, returns `-1`. If the time point `abs_time` is reached before all locks are acquired, releases any locks it holds and returns the index of the lockable for which `try_lock_until()` or `try_lock_for()` failed due to `abs_time` being reached. If a call to `try_lock_until()`, `try_lock_for()` or `try_lock()` throws an exception, `unlock()` is called on any object locked by this algorithm prior to the exception, and the exception is rethrown.<br>An implementation should ensure that `try_lock_until()` does not consistently return ≥ 0 in the absence of contending mutex acquisitions.
 
-If a call to `try_lock_until()`, `try_lock_for()` or `try_lock()` throws an exception, `unlock()` is called on any object locked by this algorithm prior to the exception, and the exception is rethrown.
+**8** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Returns*: `-1` if all locks were obtained, otherwise the index of the lockable for which `try_lock_until()` or `try_lock_for()` failed due to `abs_time` being reached.
 
-**8** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Returns*: `-1` if all locks were obtained, otherwise the index of the last lockable for which locking failed.
+**9** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Throws*: Any exception thrown by the lockable `try_lock_until()`, `try_lock_for()`, or `try_lock()` functions.
 
 ```cpp
 template <class Rep, class Period, class... Ls>
@@ -86,11 +94,7 @@ int try_lock_for(const chrono::duration<Rep, Period>& rel_time, Ls&... ls);
 
 **9** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Preconditions*: Each template parameter type in `Ls` meets the *Cpp17TimedLockable* requirements.
 
-**10** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Effects*: Equivalent to:
-
-```cpp
-return try_lock_until(chrono::steady_clock::now() + rel_time, ls...);
-```
+**10** &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;*Effects*: Equivalent to:<br>`return try_lock_until(chrono::steady_clock::now() + rel_time, ls...);`
 
 ## 6. Example
 
@@ -109,6 +113,8 @@ if (std::try_lock_for(100ms, m1, m2) == -1) {
 
 Existing implementations of `std::lock` already use a deadlock-avoidance algorithm. Using the gcc implementation as an example, instead of locking one with `m.lock()` and using `std::try_lock()` on the rest, the algorithm could start locking one with `m.try_lock_until(tp)`. [Example at Compiler Explorer](https://godbolt.org/z/Ya7Pbq85P)
 
+A reference implementation is available at [github.com/bemanproject/timed_lock_alg](https://github.com/bemanproject/timed_lock_alg).
+
 ## 8. Acknowledgments
 
 The std-proposals mailing list:
@@ -123,4 +129,4 @@ Reference implementation:
 
 ## 9. References
 
-- N5008: Working Draft, Programming Languages — C++ (C++26).
+- N5014: Working Draft, Programming Languages — C++ (C++26).

papers/P3833.md

@@ -2,7 +2,7 @@
 title: "`std::multi_lock`"
 ---
 
-- **Document number:** P3833R2a
+- **Document number:** P3833R2
 - **Date:** @DATE@
 - **Audience:** LEWGI/SG1
 - **Project:** ISO/IEC 14882 Programming Languages — C++, ISO/IEC JTC1/SC22/WG21
@@ -13,6 +13,7 @@ title: "`std::multi_lock`"
 ### R2
 
 - Removed _Attempts to lock all mutexes using a deadlock-avoidance algorithm until `abs_time`_ from `try_lock_until` _Effects_ after unanimous vote in Croydon.
+- Clarified that no call to `try_lock_for()` or `try_lock_until()` is made while holding a lock on any element of `pm` in `try_lock_until` _Effects_, to harmonize with the updated wording in P3832.
 
 ### R1
 
@@ -506,7 +507,7 @@ template<class Clock, class Duration>
 
 **14**        *Preconditions*: All types in `MutexTypes` meet the *Cpp17TimedLockable* requirements (32.2.5.4).
 
-**15**        *Effects*: If `sizeof...(MutexTypes)` equals 0, returns -1. Otherwise, if `sizeof...(MutexTypes)` equals 1, calls `get<0>(pm)->try_lock_until(abs_time)` and returns -1 if successful, 0 otherwise. Otherwise, uses an algorithm similar to `lock()` but with timed operations respecting `abs_time`.
+**15**        *Effects*: If `sizeof...(MutexTypes)` equals 0, returns -1. Otherwise, if `sizeof...(MutexTypes)` equals 1, calls `get<0>(pm)->try_lock_until(abs_time)` and returns -1 if successful, 0 otherwise. Otherwise, uses an algorithm similar to `lock()` but with timed operations respecting `abs_time`. No call to `try_lock_for()` or `try_lock_until()` is made while holding a lock on any element of `pm`.
 
 **16**        *Postconditions*: `owns` is `true` if the return value equals -1, otherwise `false`.