[thread.mutex.requirements]

Files changed (1) hide show

tmp/tmplkn231ie/{from.md → to.md} +59 -46

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

@@ -10,18 +10,20 @@ Mutexes can be either recursive or non-recursive, and can grant
 simultaneous ownership to one or many execution agents. Both recursive
 and non-recursive mutexes are supplied.
 #### 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 meet the requirements set
-out in this subclause. In this description, `m` denotes an object of a
-mutex type.
-The mutex types meet the *Cpp17Lockable* requirements
-[[thread.req.lockable.req]].
 The mutex types meet *Cpp17DefaultConstructible* and
 *Cpp17Destructible*. If initialization of an object of a mutex type
 fails, an exception of type `system_error` is thrown. The mutex types
 are neither copyable nor movable.
@@ -39,15 +41,15 @@ functions of the mutex types are as follows:
 The implementation provides 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 appears 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()` is well-formed and has the following
 semantics:
@@ -57,17 +59,17 @@ semantics:
 the mutex.
 *Effects:* Blocks the calling thread until ownership of the mutex can be
 obtained for the calling thread.
-*Ensures:* The calling thread owns the mutex.
-*Return type:* `void`.
 *Synchronization:* Prior `unlock()` operations on the same object
 *synchronize with*[[intro.multithread]] this operation.
 *Throws:* `system_error` when an exception is
 required [[thread.req.exception]].
 *Error conditions:*
@@ -93,24 +95,23 @@ interesting implementations based on a simple compare and
 exchange [[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()` is well-formed and has the following
 semantics:
@@ -152,11 +153,11 @@ 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()`.
-[*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
@@ -165,11 +166,11 @@ used to protect the reference count. — *end note*]
 The class `mutex` meets all of the mutex requirements
 [[thread.mutex.requirements]]. It is a standard-layout class
 [[class.prop]].
-[*Note 4*: A program can 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 might be
 observed. — *end note*]
 The behavior of a program is undefined if it destroys a `mutex` object
@@ -224,19 +225,21 @@ The behavior of a program is undefined if:
 - it destroys a `recursive_mutex` object owned by any thread or
 - a thread terminates while owning a `recursive_mutex` object.
 #### Timed mutex types <a id="thread.timedmutex.requirements">[[thread.timedmutex.requirements]]</a>
 The *timed mutex types* are the standard library types `timed_mutex`,
 `recursive_timed_mutex`, and `shared_timed_mutex`. They meet the
 requirements set out below. In this description, `m` denotes an object
 of a mutex type, `rel_time` denotes an object of an instantiation of
 `duration` [[time.duration]], and `abs_time` denotes an object of an
 instantiation of `time_point` [[time.point]].
-The timed mutex types meet the *Cpp17TimedLockable* requirements
-[[thread.req.lockable.timed]].
 The expression `m.try_lock_for(rel_time)` is well-formed and has the
 following semantics:
 *Preconditions:* If `m` is of type `timed_mutex` or
@@ -252,18 +255,18 @@ the mutex object.
 [*Note 1*: As with `try_lock()`, there is no guarantee that ownership
 will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
-*Return type:* `bool`.
-*Returns:* `true` if ownership was obtained, otherwise `false`.
 *Synchronization:* If `try_lock_for()` returns `true`, prior `unlock()`
 operations on the same object *synchronize with*[[intro.multithread]]
 this operation.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 The expression `m.try_lock_until(abs_time)` is well-formed and has the
 following semantics:
@@ -278,18 +281,18 @@ before the absolute timeout [[thread.req.timing]] specified by
 [*Note 2*: As with `try_lock()`, there is no guarantee that ownership
 will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
-*Return type:* `bool`.
-*Returns:* `true` if ownership was obtained, otherwise `false`.
 *Synchronization:* If `try_lock_until()` returns `true`, prior
 `unlock()` operations on the same object *synchronize
 with*[[intro.multithread]] this operation.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 ##### Class `timed_mutex` <a id="thread.timedmutex.class">[[thread.timedmutex.class]]</a>
 ``` cpp
@@ -392,16 +395,21 @@ The behavior of a program is undefined if:
 - it destroys a `recursive_timed_mutex` object owned by any thread, or
 - a thread terminates while owning a `recursive_timed_mutex` object.
 #### Shared mutex types <a id="thread.sharedmutex.requirements">[[thread.sharedmutex.requirements]]</a>
 The standard library types `shared_mutex` and `shared_timed_mutex` are
 *shared mutex types*. Shared mutex types meet the requirements of mutex
 types [[thread.mutex.requirements.mutex]] and additionally meet the
 requirements set out below. In this description, `m` denotes an object
 of a shared mutex type.
 In addition to the exclusive lock ownership mode specified in
 [[thread.mutex.requirements.mutex]], shared mutex types provide a
 *shared lock* ownership mode. Multiple execution agents can
 simultaneously hold a shared lock ownership of a shared mutex type. But
 no execution agent holds a shared lock while another execution agent
@@ -420,17 +428,17 @@ semantics:
 *Effects:* Blocks the calling thread until shared ownership of the mutex
 can be obtained for the calling thread. If an exception is thrown then a
 shared lock has not been acquired for the current thread.
-*Ensures:* The calling thread has a shared lock on the mutex.
-*Return type:* `void`.
 *Synchronization:* Prior `unlock()` operations on the same object
 synchronize with [[intro.multithread]] this operation.
 *Throws:* `system_error` when an exception is
 required [[thread.req.exception]].
 *Error conditions:*
@@ -464,19 +472,18 @@ following semantics:
 calling thread without blocking. If shared ownership is not obtained,
 there is no effect and `try_lock_shared()` immediately returns. An
 implementation may fail to obtain the lock even if it is not held by any
 other thread.
-*Return type:* `bool`.
-*Returns:* `true` if the shared ownership lock was acquired, `false`
-otherwise.
 *Synchronization:* If `try_lock_shared()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
 *Throws:* Nothing.
 ##### Class `shared_mutex` <a id="thread.sharedmutex.class">[[thread.sharedmutex.class]]</a>
 ``` cpp
@@ -522,19 +529,25 @@ The behavior of a program is undefined if:
 `shared_mutex` may be a synonym for `shared_timed_mutex`.
 #### Shared timed mutex types <a id="thread.sharedtimedmutex.requirements">[[thread.sharedtimedmutex.requirements]]</a>
 The standard library type `shared_timed_mutex` is a *shared timed mutex
 type*. Shared timed mutex types meet the requirements of timed mutex
 types [[thread.timedmutex.requirements]], shared mutex types
 [[thread.sharedmutex.requirements]], and additionally meet the
 requirements set out below. In this description, `m` denotes an object
-of a shared timed mutex type, `rel_type` denotes an object of an
 instantiation of `duration` [[time.duration]], and `abs_time` denotes an
 object of an instantiation of `time_point` [[time.point]].
 The expression `m.try_lock_shared_for(rel_time)` is well-formed and has
 the following semantics:
 *Preconditions:* The calling thread has no ownership of the mutex.
@@ -551,18 +564,18 @@ will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
 If an exception is thrown then a shared lock has not been acquired for
 the current thread.
-*Return type:* `bool`.
-*Returns:* `true` if the shared lock was acquired, `false` otherwise.
 *Synchronization:* If `try_lock_shared_for()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 The expression `m.try_lock_shared_until(abs_time)` is well-formed and
 has the following semantics:
@@ -580,18 +593,18 @@ will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
 If an exception is thrown then a shared lock has not been acquired for
 the current thread.
-*Return type:* `bool`.
-*Returns:* `true` if the shared lock was acquired, `false` otherwise.
 *Synchronization:* If `try_lock_shared_until()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 ##### Class `shared_timed_mutex` <a id="thread.sharedtimedmutex.class">[[thread.sharedtimedmutex.class]]</a>
 ``` cpp

 simultaneous ownership to one or many execution agents. Both recursive
 and non-recursive mutexes are supplied.
 #### Mutex types <a id="thread.mutex.requirements.mutex">[[thread.mutex.requirements.mutex]]</a>
+##### General <a id="thread.mutex.requirements.mutex.general">[[thread.mutex.requirements.mutex.general]]</a>
 The *mutex types* are the standard library types `mutex`,
 `recursive_mutex`, `timed_mutex`, `recursive_timed_mutex`,
 `shared_mutex`, and `shared_timed_mutex`. They meet the requirements set
+out in [[thread.mutex.requirements.mutex]]. In this description, `m`
+denotes an object of a mutex type.
+[*Note 1*: The mutex types meet the *Cpp17Lockable* requirements
+[[thread.req.lockable.req]]. — *end note*]
 The mutex types meet *Cpp17DefaultConstructible* and
 *Cpp17Destructible*. If initialization of an object of a mutex type
 fails, an exception of type `system_error` is thrown. The mutex types
 are neither copyable nor movable.
 The implementation provides 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 appears to occur in a single total order.
+[*Note 2*: This can be viewed as the modification order
 [[intro.multithread]] of the mutex. — *end note*]
+[*Note 3*: Construction and destruction of an object of a mutex type
+need not be thread-safe; other synchronization can be used to ensure
 that mutex objects are initialized and visible to other
 threads. — *end note*]
 The expression `m.lock()` is well-formed and has the following
 semantics:
 the mutex.
 *Effects:* Blocks the calling thread until ownership of the mutex can be
 obtained for the calling thread.
 *Synchronization:* Prior `unlock()` operations on the same object
 *synchronize with*[[intro.multithread]] this operation.
+*Ensures:* The calling thread owns the mutex.
+*Return type:* `void`.
 *Throws:* `system_error` when an exception is
 required [[thread.req.exception]].
 *Error conditions:*
 exchange [[atomics]]. — *end note*]
 An implementation should ensure that `try_lock()` does not consistently
 return `false` in the absence of contending mutex acquisitions.
 *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*]
+*Return type:* `bool`.
+*Returns:* `true` if ownership was obtained, otherwise `false`.
 *Throws:* Nothing.
 The expression `m.unlock()` is well-formed and has the following
 semantics:
 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 4*: 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
 The class `mutex` meets all of the mutex requirements
 [[thread.mutex.requirements]]. It is a standard-layout class
 [[class.prop]].
+[*Note 5*: A program can 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 might be
 observed. — *end note*]
 The behavior of a program is undefined if it destroys a `mutex` object
 - it destroys a `recursive_mutex` object owned by any thread or
 - a thread terminates while owning a `recursive_mutex` object.
 #### Timed mutex types <a id="thread.timedmutex.requirements">[[thread.timedmutex.requirements]]</a>
+##### General <a id="thread.timedmutex.requirements.general">[[thread.timedmutex.requirements.general]]</a>
 The *timed mutex types* are the standard library types `timed_mutex`,
 `recursive_timed_mutex`, and `shared_timed_mutex`. They meet the
 requirements set out below. In this description, `m` denotes an object
 of a mutex type, `rel_time` denotes an object of an instantiation of
 `duration` [[time.duration]], and `abs_time` denotes an object of an
 instantiation of `time_point` [[time.point]].
+[*Note 1*: The timed mutex types meet the *Cpp17TimedLockable*
+requirements [[thread.req.lockable.timed]]. — *end note*]
 The expression `m.try_lock_for(rel_time)` is well-formed and has the
 following semantics:
 *Preconditions:* If `m` is of type `timed_mutex` or
 [*Note 1*: As with `try_lock()`, there is no guarantee that ownership
 will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
 *Synchronization:* If `try_lock_for()` returns `true`, prior `unlock()`
 operations on the same object *synchronize with*[[intro.multithread]]
 this operation.
+*Return type:* `bool`.
+*Returns:* `true` if ownership was obtained, otherwise `false`.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 The expression `m.try_lock_until(abs_time)` is well-formed and has the
 following semantics:
 [*Note 2*: As with `try_lock()`, there is no guarantee that ownership
 will be obtained if the lock is available, but implementations are
 expected to make a strong effort to do so. — *end note*]
 *Synchronization:* If `try_lock_until()` returns `true`, prior
 `unlock()` operations on the same object *synchronize
 with*[[intro.multithread]] this operation.
+*Return type:* `bool`.
+*Returns:* `true` if ownership was obtained, otherwise `false`.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 ##### Class `timed_mutex` <a id="thread.timedmutex.class">[[thread.timedmutex.class]]</a>
 ``` cpp
 - it destroys a `recursive_timed_mutex` object owned by any thread, or
 - a thread terminates while owning a `recursive_timed_mutex` object.
 #### Shared mutex types <a id="thread.sharedmutex.requirements">[[thread.sharedmutex.requirements]]</a>
+##### General <a id="thread.sharedmutex.requirements.general">[[thread.sharedmutex.requirements.general]]</a>
 The standard library types `shared_mutex` and `shared_timed_mutex` are
 *shared mutex types*. Shared mutex types meet the requirements of mutex
 types [[thread.mutex.requirements.mutex]] and additionally meet the
 requirements set out below. In this description, `m` denotes an object
 of a shared mutex type.
+[*Note 1*: The shared mutex types meet the *Cpp17SharedLockable*
+requirements [[thread.req.lockable.shared]]. — *end note*]
 In addition to the exclusive lock ownership mode specified in
 [[thread.mutex.requirements.mutex]], shared mutex types provide a
 *shared lock* ownership mode. Multiple execution agents can
 simultaneously hold a shared lock ownership of a shared mutex type. But
 no execution agent holds a shared lock while another execution agent
 *Effects:* Blocks the calling thread until shared ownership of the mutex
 can be obtained for the calling thread. If an exception is thrown then a
 shared lock has not been acquired for the current thread.
 *Synchronization:* Prior `unlock()` operations on the same object
 synchronize with [[intro.multithread]] this operation.
+*Ensures:* The calling thread has a shared lock on the mutex.
+*Return type:* `void`.
 *Throws:* `system_error` when an exception is
 required [[thread.req.exception]].
 *Error conditions:*
 calling thread without blocking. If shared ownership is not obtained,
 there is no effect and `try_lock_shared()` immediately returns. An
 implementation may fail to obtain the lock even if it is not held by any
 other thread.
 *Synchronization:* If `try_lock_shared()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
+*Return type:* `bool`.
+*Returns:* `true` if the shared lock was acquired, otherwise `false`.
 *Throws:* Nothing.
 ##### Class `shared_mutex` <a id="thread.sharedmutex.class">[[thread.sharedmutex.class]]</a>
 ``` cpp
 `shared_mutex` may be a synonym for `shared_timed_mutex`.
 #### Shared timed mutex types <a id="thread.sharedtimedmutex.requirements">[[thread.sharedtimedmutex.requirements]]</a>
+##### General <a id="thread.sharedtimedmutex.requirements.general">[[thread.sharedtimedmutex.requirements.general]]</a>
 The standard library type `shared_timed_mutex` is a *shared timed mutex
 type*. Shared timed mutex types meet the requirements of timed mutex
 types [[thread.timedmutex.requirements]], shared mutex types
 [[thread.sharedmutex.requirements]], and additionally meet the
 requirements set out below. In this description, `m` denotes an object
+of a shared timed mutex type, `rel_time` denotes an object of an
 instantiation of `duration` [[time.duration]], and `abs_time` denotes an
 object of an instantiation of `time_point` [[time.point]].
+[*Note 1*: The shared timed mutex types meet the
+*Cpp17SharedTimedLockable* requirements
+[[thread.req.lockable.shared.timed]]. — *end note*]
 The expression `m.try_lock_shared_for(rel_time)` is well-formed and has
 the following semantics:
 *Preconditions:* The calling thread has no ownership of the mutex.
 expected to make a strong effort to do so. — *end note*]
 If an exception is thrown then a shared lock has not been acquired for
 the current thread.
 *Synchronization:* If `try_lock_shared_for()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
+*Return type:* `bool`.
+*Returns:* `true` if the shared lock was acquired, otherwise `false`.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 The expression `m.try_lock_shared_until(abs_time)` is well-formed and
 has the following semantics:
 expected to make a strong effort to do so. — *end note*]
 If an exception is thrown then a shared lock has not been acquired for
 the current thread.
 *Synchronization:* If `try_lock_shared_until()` returns `true`, prior
 `unlock()` operations on the same object synchronize
 with [[intro.multithread]] this operation.
+*Return type:* `bool`.
+*Returns:* `true` if the shared lock was acquired, otherwise `false`.
 *Throws:* Timeout-related exceptions [[thread.req.timing]].
 ##### Class `shared_timed_mutex` <a id="thread.sharedtimedmutex.class">[[thread.sharedtimedmutex.class]]</a>
 ``` cpp

Diff to HTML by rtfpessoa