30 Thread support library [thread]

Throughout this Clause, the names of template parameters are used to express type requirements. If a template parameter is named Predicate, operator() applied to the template argument shall return a value that is convertible to bool.

Some functions described in this Clause are specified to throw exceptions of type system_error ([syserr.syserr]). Such exceptions shall be 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 shall be reported as described in [res.on.exception.handling].

[ Example: 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 ]

The error_code reported by such an exception's code() member function shall compare equal to one of the conditions specified in the function's error condition element.

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: 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 ]

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].

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 D_i. Ideally, this delay would be zero. Further, any contention for processor and memory resources induces a “quality of management” delay, expressed as duration D_m. The delay durations may vary from timeout to timeout, but in all cases shorter is better.

The member 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.337 Given a duration argument D_t, the real-time duration of the timeout is D_t + D_i + D_m.

The member 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 C_t, the clock time point of the return from timeout should be C_t + D_i + D_m when the clock is not adjusted during the timeout. If the clock is adjusted to the time C_a during the timeout, the behavior should be as follows:

• (4.1)

  if C_a > C_t, the waiting function should wake as soon as possible, i.e. C_a + D_i + D_m, since the timeout is already satisfied. [ Note: This specification may result in the total duration of the wait decreasing when measured against a steady clock.  — end note ]

• (4.2)

  if C_a <= C_t, the waiting function should not time out until Clock::now() returns a time C_n >= C_t, i.e. waking at C_t + D_i + D_m. [ Note: When the clock is adjusted backwards, this specification may result in the total duration of the wait increasing when measured against a steady clock. When the clock is adjusted forwards, this specification may result in the total duration of the wait decreasing when measured against a steady clock.  — end note ]

An implementation shall return 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 C_t and the time point of the call to the _until function. [ Note: Implementations should decrease the duration of the wait when the clock is adjusted forwards.  — end note ]

[ Note: If the clock is not synchronized with a steady clock, e.g., a CPU time clock, these timeouts might not provide useful functionality.  — end note ]

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.

Implementation-provided clocks that are used for these functions shall meet the TrivialClock requirements ([time.clock.req]).

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: instantiations of clock, time point and duration types supplied by the implementation as specified in [time.clock] do not throw exceptions.  — end note ]

In several places in this Clause the operation DECAY_COPY(x) is used. All such uses mean call the function decay_copy(x) and use the result, where decay_copy is defined as follows:

template <class T> decay_t<T> decay_copy(T&& v)
  { return std::forward<T>(v); }