[thread.mutex.requirements.mutex]

Files changed (1) hide show

tmp/tmp1kjm96xc/{from.md → to.md} +52 -47

tmp/tmp1kjm96xc/{from.md → to.md} RENAMED Viewed

@@ -1,12 +1,12 @@
 #### Mutex types <a id="thread.mutex.requirements.mutex">[[thread.mutex.requirements.mutex]]</a>
-The *mutex types* are the standard library types `std::mutex`,
-`std::recursive_mutex`, `std::timed_mutex`,
-`std::recursive_timed_mutex`, and `std::shared_timed_mutex`. They shall
-meet the requirements set out in this section. In this description, `m`
-denotes an object of a mutex type.
 The mutex types shall meet the `Lockable` requirements (
 [[thread.req.lockable.req]]).
 The mutex types shall be `DefaultConstructible` and `Destructible`. If
@@ -19,37 +19,39 @@ functions of the mutex types shall be:
 - `resource_unavailable_try_again` — if any native handle type
   manipulated is not available.
 - `operation_not_permitted` — if the thread does not have the privilege
   to perform the operation.
-- `device_or_resource_busy` — if any native handle type manipulated is
-  already locked.
 - `invalid_argument` — if any native handle type manipulated as part of
   mutex construction is incorrect.
 The implementation shall provide lock and unlock operations, as
 described below. For purposes of determining the existence of a data
 race, these behave as atomic operations ([[intro.multithread]]). The
 lock and unlock operations on a single mutex shall appear to occur in a
-single total order. this can be viewed as the modification order (
-[[intro.multithread]]) of the mutex. Construction and destruction of an
-object of a mutex type need not be thread-safe; other synchronization
-should be used to ensure that mutex objects are initialized and visible
-to other threads.
 The expression `m.lock()` shall be well-formed and have the following
 semantics:
-*Requires:* If `m` is of type `std::mutex`, `std::timed_mutex`, or
-`std::shared_timed_mutex`, the calling thread does not own the mutex.
 *Effects:* Blocks the calling thread until ownership of the mutex can be
 obtained for the calling thread.
-The calling thread owns the mutex.
-*Return type:* `void`
 *Synchronization:* Prior `unlock()` operations on the same object shall
 *synchronize with* ([[intro.multithread]]) this operation.
 *Throws:* `system_error` when an exception is
@@ -59,51 +61,53 @@ required ([[thread.req.exception]]).
 - `operation_not_permitted` — if the thread does not have the privilege
   to perform the operation.
 - `resource_deadlock_would_occur` — if the implementation detects that a
   deadlock would occur.
-- `device_or_resource_busy` — if the mutex is already locked and
-  blocking is not possible.
 The expression `m.try_lock()` shall be well-formed and have the
 following semantics:
-*Requires:* If `m` is of type `std::mutex`, `std::timed_mutex`, or
-`std::shared_timed_mutex`, the calling thread does not own the mutex.
 *Effects:* Attempts to obtain ownership of the mutex for the calling
 thread without blocking. If ownership is not obtained, there is no
 effect and `try_lock()` immediately returns. An implementation may fail
-to obtain the lock even if it is not held by any other thread. This
-spurious failure is normally uncommon, but allows interesting
-implementations based on a simple compare and exchange
-(Clause  [[atomics]]). An implementation should ensure that `try_lock()`
-does not consistently return `false` in the absence of contending mutex
-acquisitions.
-*Return type:* `bool`
 *Returns:* `true` if ownership of the mutex was obtained for the calling
 thread, otherwise `false`.
 *Synchronization:* If `try_lock()` returns `true`, prior `unlock()`
 operations on the same object *synchronize
-with* ([[intro.multithread]]) this operation. Since `lock()` does not
-synchronize with a failed subsequent `try_lock()`, the visibility rules
-are weak enough that little would be known about the state after a
-failure, even in the absence of spurious failures.
 *Throws:* Nothing.
 The expression `m.unlock()` shall be well-formed and have the following
 semantics:
-The calling thread shall own the mutex.
 *Effects:* Releases the calling thread’s ownership of the mutex.
-*Return type:* `void`
 *Synchronization:* This operation synchronizes
 with ([[intro.multithread]]) subsequent lock operations that obtain
 ownership on the same object.
@@ -123,11 +127,11 @@ namespace std {
     void lock();
     bool try_lock();
     void unlock();
- typedef implementation-defined native_handle_type; // See~[thread.req.native]
     native_handle_type native_handle();                // See~[thread.req.native]
   };
 }
 ```
@@ -135,26 +139,27 @@ The class `mutex` provides a non-recursive mutex with exclusive
 ownership semantics. If one thread owns a mutex object, attempts by
 another thread to acquire ownership of that object will fail (for
 `try_lock()`) or block (for `lock()`) until the owning thread has
 released ownership with a call to `unlock()`.
-After a thread `A` has called `unlock()`, releasing a mutex, it is
-possible for another thread `B` to lock the same mutex, observe that it
-is no longer in use, unlock it, and destroy it, before thread `A`
-appears to have returned from its unlock call. Implementations are
 required to handle such scenarios correctly, as long as thread `A`
 doesn’t access the mutex after the unlock call returns. These cases
 typically occur when a reference-counted object contains a mutex that is
-used to protect the reference count.
-The class `mutex` shall satisfy all the `Mutex` requirements (
 [[thread.mutex.requirements]]). It shall be a standard-layout class
 (Clause  [[class]]).
-A program may deadlock if the thread that owns a `mutex` object calls
-`lock()` on that object. If the implementation can detect the deadlock,
-a `resource_deadlock_would_occur` error condition may be observed.
 The behavior of a program is undefined if it destroys a `mutex` object
 owned by any thread or a thread terminates while owning a `mutex`
 object.
@@ -172,11 +177,11 @@ namespace std {
     void lock();
     bool try_lock() noexcept;
     void unlock();
- typedef implementation-defined native_handle_type; // See~[thread.req.native]
     native_handle_type native_handle();                // See~[thread.req.native]
   };
 }
 ```
@@ -184,13 +189,13 @@ The class `recursive_mutex` provides a recursive mutex with exclusive
 ownership semantics. If one thread owns a `recursive_mutex` object,
 attempts by another thread to acquire ownership of that object will fail
 (for `try_lock()`) or block (for `lock()`) until the first thread has
 completely released ownership.
-The class `recursive_mutex` shall satisfy all the Mutex requirements (
-[[thread.mutex.requirements]]). It shall be a standard-layout class
-(Clause  [[class]]).
 A thread that owns a `recursive_mutex` object may acquire additional
 levels of ownership by calling `lock()` or `try_lock()` on that object.
 It is unspecified how many levels of ownership may be acquired by a
 single thread. If a thread has already acquired the maximum level of

 #### Mutex types <a id="thread.mutex.requirements.mutex">[[thread.mutex.requirements.mutex]]</a>
+The *mutex types* are the standard library types `mutex`,
+`recursive_mutex`, `timed_mutex`, `recursive_timed_mutex`,
+`shared_mutex`, and `shared_timed_mutex`. They shall meet the
+requirements set out in this section. In this description, `m` denotes
+an object of a mutex type.
 The mutex types shall meet the `Lockable` requirements (
 [[thread.req.lockable.req]]).
 The mutex types shall be `DefaultConstructible` and `Destructible`. If
 - `resource_unavailable_try_again` — if any native handle type
   manipulated is not available.
 - `operation_not_permitted` — if the thread does not have the privilege
   to perform the operation.
 - `invalid_argument` — if any native handle type manipulated as part of
   mutex construction is incorrect.
 The implementation shall provide lock and unlock operations, as
 described below. For purposes of determining the existence of a data
 race, these behave as atomic operations ([[intro.multithread]]). The
 lock and unlock operations on a single mutex shall appear to occur in a
+single total order.
+[*Note 1*: This can be viewed as the modification order (
+[[intro.multithread]]) of the mutex. — *end note*]
+[*Note 2*: Construction and destruction of an object of a mutex type
+need not be thread-safe; other synchronization should be used to ensure
+that mutex objects are initialized and visible to other
+threads. — *end note*]
 The expression `m.lock()` shall be well-formed and have the following
 semantics:
+*Requires:* If `m` is of type `mutex`, `timed_mutex`, `shared_mutex`, or
+`shared_timed_mutex`, the calling thread does not own the mutex.
 *Effects:* Blocks the calling thread until ownership of the mutex can be
 obtained for the calling thread.
+*Postconditions:* The calling thread owns the mutex.
+*Return type:* `void`.
 *Synchronization:* Prior `unlock()` operations on the same object shall
 *synchronize with* ([[intro.multithread]]) this operation.
 *Throws:* `system_error` when an exception is
 - `operation_not_permitted` — if the thread does not have the privilege
   to perform the operation.
 - `resource_deadlock_would_occur` — if the implementation detects that a
   deadlock would occur.
 The expression `m.try_lock()` shall be well-formed and have the
 following semantics:
+*Requires:* If `m` is of type `mutex`, `timed_mutex`, `shared_mutex`, or
+`shared_timed_mutex`, the calling thread does not own the mutex.
 *Effects:* Attempts to obtain ownership of the mutex for the calling
 thread without blocking. If ownership is not obtained, there is no
 effect and `try_lock()` immediately returns. An implementation may fail
+to obtain the lock even if it is not held by any other thread.
+[*Note 1*: This spurious failure is normally uncommon, but allows
+interesting implementations based on a simple compare and exchange
+(Clause  [[atomics]]). — *end note*]
+An implementation should ensure that `try_lock()` does not consistently
+return `false` in the absence of contending mutex acquisitions.
+*Return type:* `bool`.
 *Returns:* `true` if ownership of the mutex was obtained for the calling
 thread, otherwise `false`.
 *Synchronization:* If `try_lock()` returns `true`, prior `unlock()`
 operations on the same object *synchronize
+with* ([[intro.multithread]]) this operation.
+[*Note 2*: Since `lock()` does not synchronize with a failed subsequent
+`try_lock()`, the visibility rules are weak enough that little would be
+known about the state after a failure, even in the absence of spurious
+failures. — *end note*]
 *Throws:* Nothing.
 The expression `m.unlock()` shall be well-formed and have the following
 semantics:
+*Requires:* The calling thread shall own the mutex.
 *Effects:* Releases the calling thread’s ownership of the mutex.
+*Return type:* `void`.
 *Synchronization:* This operation synchronizes
 with ([[intro.multithread]]) subsequent lock operations that obtain
 ownership on the same object.
     void lock();
     bool try_lock();
     void unlock();
+ using native_handle_type = implementation-defined; // See~[thread.req.native]
     native_handle_type native_handle();                // See~[thread.req.native]
   };
 }
 ```
 ownership semantics. If one thread owns a mutex object, attempts by
 another thread to acquire ownership of that object will fail (for
 `try_lock()`) or block (for `lock()`) until the owning thread has
 released ownership with a call to `unlock()`.
+[*Note 3*: After a thread `A` has called `unlock()`, releasing a mutex,
+it is possible for another thread `B` to lock the same mutex, observe
+that it is no longer in use, unlock it, and destroy it, before thread
+`A` appears to have returned from its unlock call. Implementations are
 required to handle such scenarios correctly, as long as thread `A`
 doesn’t access the mutex after the unlock call returns. These cases
 typically occur when a reference-counted object contains a mutex that is
+used to protect the reference count. — *end note*]
+The class `mutex` shall satisfy all of the mutex requirements (
 [[thread.mutex.requirements]]). It shall be a standard-layout class
 (Clause  [[class]]).
+[*Note 4*: A program may deadlock if the thread that owns a `mutex`
+object calls `lock()` on that object. If the implementation can detect
+the deadlock, a `resource_deadlock_would_occur` error condition may be
+observed. — *end note*]
 The behavior of a program is undefined if it destroys a `mutex` object
 owned by any thread or a thread terminates while owning a `mutex`
 object.
     void lock();
     bool try_lock() noexcept;
     void unlock();
+ using native_handle_type = implementation-defined; // See~[thread.req.native]
     native_handle_type native_handle();                // See~[thread.req.native]
   };
 }
 ```
 ownership semantics. If one thread owns a `recursive_mutex` object,
 attempts by another thread to acquire ownership of that object will fail
 (for `try_lock()`) or block (for `lock()`) until the first thread has
 completely released ownership.
+The class `recursive_mutex` shall satisfy all of the mutex
+requirements ([[thread.mutex.requirements]]). It shall be a
+standard-layout class (Clause  [[class]]).
 A thread that owns a `recursive_mutex` object may acquire additional
 levels of ownership by calling `lock()` or `try_lock()` on that object.
 It is unspecified how many levels of ownership may be acquired by a
 single thread. If a thread has already acquired the maximum level of

Diff to HTML by rtfpessoa