33 Concurrency support library [thread]

33.2 Requirements [thread.req]

33.2.1 Template parameter names [thread.req.paramname]

1
#
Throughout this Clause, the names of template parameters are used to express type requirements.
Predicate is a function object type ([function.objects]).
Let pred denote an lvalue of type Predicate.
Then the expression pred() shall be well-formed and the type decltype(pred()) shall model boolean-testable ([concept.booleantestable]).
The return value of pred(), converted to bool, yields true if the corresponding test condition is satisfied, and false otherwise.
If a template parameter is named Clock, the corresponding template argument shall be a type C that meets the Cpp17Clock requirements ([time.clock.req]); the program is ill-formed if is_clock_v<C> is false.

33.2.2 Exceptions [thread.req.exception]

1
#
Some functions described in this Clause are specified to throw exceptions of type system_error ([syserr.syserr]).
Such exceptions are thrown if any of the function's error conditions is detected or a call to an operating system or other underlying API results in an error that prevents the library function from meeting its specifications.
Failure to allocate storage is reported as described in [res.on.exception.handling].
[Example 1: 
Consider a function in this Clause that is specified to throw exceptions of type system_error and specifies error conditions that include operation_not_permitted for a thread that does not have the privilege to perform the operation.
Assume that, during the execution of this function, an errno of EPERM is reported by a POSIX API call used by the implementation.
Since POSIX specifies an errno of EPERM when “the caller does not have the privilege to perform the operation”, the implementation maps EPERM to an error_condition of operation_not_permitted ([syserr]) and an exception of type system_error is thrown.
— end example]
2
#
The error_code reported by such an exception's code() member function compares equal to one of the conditions specified in the function's error condition element.

33.2.3 Native handles [thread.req.native]

1
#
Several classes described in this Clause have members native_handle_type and native_handle.
The presence of these members and their semantics is implementation-defined.
[Note 1: 
These members allow implementations to provide access to implementation details.
Their names are specified to facilitate portable compile-time detection.
Actual use of these members is inherently non-portable.
— end note]

33.2.4 Timing specifications [thread.req.timing]

1
#
Several functions described in this Clause take an argument to specify a timeout.
These timeouts are specified as either a duration or a time_point type as specified in [time].
2
#
Implementations necessarily have some delay in returning from a timeout.
Any overhead in interrupt response, function return, and scheduling induces a “quality of implementation” delay, expressed as duration .
Ideally, this delay would be zero.
Further, any contention for processor and memory resources induces a “quality of management” delay, expressed as duration .
The delay durations may vary from timeout to timeout, but in all cases shorter is better.
3
#
The functions whose names end in _for take an argument that specifies a duration.
These functions produce relative timeouts.
Implementations should use a steady clock to measure time for these functions.303
Given a duration argument , the real-time duration of the timeout is .
4
#
The functions whose names end in _until take an argument that specifies a time point.
These functions produce absolute timeouts.
Implementations should use the clock specified in the time point to measure time for these functions.
Given a clock time point argument , the clock time point of the return from timeout should be when the clock is not adjusted during the timeout.
If the clock is adjusted to the time during the timeout, the behavior should be as follows:
  • (4.1)
    If , the waiting function should wake as soon as possible, i.e., , since the timeout is already satisfied.
    This specification may result in the total duration of the wait decreasing when measured against a steady clock.
  • (4.2)
    If , the waiting function should not time out until Clock​::​now() returns a time , i.e., waking at .
    [Note 1: 
    When the clock is adjusted backwards, this specification can result in the total duration of the wait increasing when measured against a steady clock.
    When the clock is adjusted forwards, this specification can result in the total duration of the wait decreasing when measured against a steady clock.
    — end note]
An implementation returns from such a timeout at any point from the time specified above to the time it would return from a steady-clock relative timeout on the difference between and the time point of the call to the _until function.
Recommended practice: Implementations should decrease the duration of the wait when the clock is adjusted forwards.
5
#
[Note 2: 
If the clock is not synchronized with a steady clock, e.g., a CPU time clock, these timeouts can fail to provide useful functionality.
— end note]
6
#
The resolution of timing provided by an implementation depends on both operating system and hardware.
The finest resolution provided by an implementation is called the native resolution.
7
#
Implementation-provided clocks that are used for these functions meet the Cpp17TrivialClock requirements ([time.clock.req]).
8
#
A function that takes an argument which specifies a timeout will throw if, during its execution, a clock, time point, or time duration throws an exception.
Such exceptions are referred to as timeout-related exceptions.
[Note 3: 
Instantiations of clock, time point and duration types supplied by the implementation as specified in [time.clock] do not throw exceptions.
— end note]
303)303)
Implementations for which standard time units are meaningful will typically have a steady clock within their hardware implementation.

33.2.5 Requirements for Cpp17Lockable types [thread.req.lockable]

33.2.5.1 In general [thread.req.lockable.general]

1
#
An execution agent is an entity such as a thread that may perform work in parallel with other execution agents.
[Note 1: 
Implementations or users can introduce other kinds of agents such as processes or thread-pool tasks.
— end note]
The calling agent is determined by context, e.g., the calling thread that contains the call, and so on.
2
#
[Note 2: 
Some lockable objects are “agent oblivious” in that they work for any execution agent model because they do not determine or store the agent's ID (e.g., an ordinary spin lock).
— end note]
3
#
The standard library templates unique_lock ([thread.lock.unique]), shared_lock ([thread.lock.shared]), scoped_lock ([thread.lock.scoped]), lock_guard ([thread.lock.guard]), lock, try_lock ([thread.lock.algorithm]), and condition_variable_any ([thread.condition.condvarany]) all operate on user-supplied lockable objects.
The Cpp17BasicLockable requirements, the Cpp17Lockable requirements, the Cpp17TimedLockable requirements, the Cpp17SharedLockable requirements, and the Cpp17SharedTimedLockable requirements list the requirements imposed by these library types in order to acquire or release ownership of a lock by a given execution agent.
[Note 3: 
The nature of any lock ownership and any synchronization it entails are not part of these requirements.
— end note]
4
#
A lock on an object m is said to be
  • (4.1)
    a non-shared lock if it is acquired by a call to lock, try_lock, try_lock_for, or try_lock_until on m, or
  • (4.2)
    a shared lock if it is acquired by a call to lock_shared, try_lock_shared, try_lock_shared_for, or try_lock_shared_until on m.
[Note 4: 
Only the method of lock acquisition is considered; the nature of any lock ownership is not part of these definitions.
— end note]

33.2.5.2 Cpp17BasicLockable requirements [thread.req.lockable.basic]

1
#
A type L meets the Cpp17BasicLockable requirements if the following expressions are well-formed and have the specified semantics (m denotes a value of type L).
🔗
m.lock()
2
#
Effects: Blocks until a lock can be acquired for the current execution agent.
If an exception is thrown then a lock shall not have been acquired for the current execution agent.
🔗
m.unlock()
3
#
Preconditions: The current execution agent holds a non-shared lock on m.
4
#
Effects: Releases a non-shared lock on m held by the current execution agent.
5
#
Throws: Nothing.

33.2.5.3 Cpp17Lockable requirements [thread.req.lockable.req]

1
#
A type L meets the Cpp17Lockable requirements if it meets the Cpp17BasicLockable requirements and the following expressions are well-formed and have the specified semantics (m denotes a value of type L).
🔗
m.try_lock()
2
#
Effects: Attempts to acquire a lock for the current execution agent without blocking.
If an exception is thrown then a lock shall not have been acquired for the current execution agent.
3
#
Return type: bool.
4
#
Returns: true if the lock was acquired, otherwise false.

33.2.5.4 Cpp17TimedLockable requirements [thread.req.lockable.timed]

1
#
A type L meets the Cpp17TimedLockable requirements if it meets the Cpp17Lockable requirements and the following expressions are well-formed and have the specified semantics (m denotes a value of type L, rel_time denotes a value of an instantiation of duration, and abs_time denotes a value of an instantiation of time_point).
🔗
m.try_lock_for(rel_time)
2
#
Effects: Attempts to acquire a lock for the current execution agent within the relative timeout ([thread.req.timing]) specified by rel_time.
The function will not return within the timeout specified by rel_time unless it has obtained a lock on m for the current execution agent.
If an exception is thrown then a lock has not been acquired for the current execution agent.
3
#
Return type: bool.
4
#
Returns: true if the lock was acquired, otherwise false.
🔗
m.try_lock_until(abs_time)
5
#
Effects: Attempts to acquire a lock for the current execution agent before the absolute timeout ([thread.req.timing]) specified by abs_time.
The function will not return before the timeout specified by abs_time unless it has obtained a lock on m for the current execution agent.
If an exception is thrown then a lock has not been acquired for the current execution agent.
6
#
Return type: bool.
7
#
Returns: true if the lock was acquired, otherwise false.

33.2.5.5 Cpp17SharedLockable requirements [thread.req.lockable.shared]

1
#
A type L meets the Cpp17SharedLockable requirements if the following expressions are well-formed, have the specified semantics, and the expression m.try_lock_shared() has type bool (m denotes a value of type L):
🔗
m.lock_shared()
2
#
Effects: Blocks until a lock can be acquired for the current execution agent.
If an exception is thrown then a lock shall not have been acquired for the current execution agent.
🔗
m.try_lock_shared()
3
#
Effects: Attempts to acquire a lock for the current execution agent without blocking.
If an exception is thrown then a lock shall not have been acquired for the current execution agent.
4
#
Returns: true if the lock was acquired, false otherwise.
🔗
m.unlock_shared()
5
#
Preconditions: The current execution agent holds a shared lock on m.
6
#
Effects: Releases a shared lock on m held by the current execution agent.
7
#
Throws: Nothing.

33.2.5.6 Cpp17SharedTimedLockable requirements [thread.req.lockable.shared.timed]

1
#
A type L meets the Cpp17SharedTimedLockable requirements if it meets the Cpp17SharedLockable requirements, and the following expressions are well-formed, have type bool, and have the specified semantics (m denotes a value of type L, rel_time denotes a value of a specialization of chrono​::​duration, and abs_time denotes a value of a specialization of chrono​::​time_point).
🔗
m.try_lock_shared_for(rel_time)
2
#
Effects: Attempts to acquire a lock for the current execution agent within the relative timeout ([thread.req.timing]) specified by rel_time.
The function will not return within the timeout specified by rel_time unless it has obtained a lock on m for the current execution agent.
If an exception is thrown then a lock has not been acquired for the current execution agent.
3
#
Returns: true if the lock was acquired, false otherwise.
🔗
m.try_lock_shared_until(abs_time)
4
#
Effects: Attempts to acquire a lock for the current execution agent before the absolute timeout ([thread.req.timing]) specified by abs_time.
The function will not return before the timeout specified by abs_time unless it has obtained a lock on m for the current execution agent.
If an exception is thrown then a lock has not been acquired for the current execution agent.
5
#
Returns: true if the lock was acquired, false otherwise.