30 Thread support library [thread]

30.3 Threads [thread.threads]

1
#
[thread.threads] describes components that can be used to create and manage threads.
[ Note
:
These threads are intended to map one-to-one with operating system threads.
— end note
 ]

30.3.1 Header <thread> synopsis [thread.syn]

namespace std {
  class thread;

  void swap(thread& x, thread& y) noexcept;

  namespace this_thread {
    thread::id get_id() noexcept;

    void yield() noexcept;
    template<class Clock, class Duration>
      void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
    template<class Rep, class Period>
      void sleep_for(const chrono::duration<Rep, Period>& rel_time);
  }
}

30.3.2 Class thread [thread.thread.class]

1
#
The class thread provides a mechanism to create a new thread of execution, to join with a thread (i.e., wait for a thread to complete), and to perform other operations that manage and query the state of a thread. A thread object uniquely represents a particular thread of execution.
That representation may be transferred to other thread objects in such a way that no two thread objects simultaneously represent the same thread of execution.
A thread of execution is detached when no thread object represents that thread.
Objects of class thread can be in a state that does not represent a thread of execution.
[ Note
:
A thread object does not represent a thread of execution after default construction, after being moved from, or after a successful call to detach or join.
— end note
 ]
namespace std {
  class thread {
  public:
    // types
    class id;
    using native_handle_type = implementation-defined;         // see [thread.req.native]

    // construct/copy/destroy
    thread() noexcept;
    template<class F, class... Args> explicit thread(F&& f, Args&&... args);
    ~thread();
    thread(const thread&) = delete;
    thread(thread&&) noexcept;
    thread& operator=(const thread&) = delete;
    thread& operator=(thread&&) noexcept;

    // members
    void swap(thread&) noexcept;
    bool joinable() const noexcept;
    void join();
    void detach();
    id get_id() const noexcept;
    native_handle_type native_handle();                         // see [thread.req.native]

    // static members
    static unsigned int hardware_concurrency() noexcept;
  };
}

30.3.2.1 Class thread​::​id [thread.thread.id]

namespace std {
  class thread::id {
  public:
    id() noexcept;
  };

  bool operator==(thread::id x, thread::id y) noexcept;
  bool operator!=(thread::id x, thread::id y) noexcept;
  bool operator<(thread::id x, thread::id y) noexcept;
  bool operator>(thread::id x, thread::id y) noexcept;
  bool operator<=(thread::id x, thread::id y) noexcept;
  bool operator>=(thread::id x, thread::id y) noexcept;

  template<class charT, class traits>
    basic_ostream<charT, traits>&
      operator<<(basic_ostream<charT, traits>& out, thread::id id);

  // hash support
  template<class T> struct hash;
  template<> struct hash<thread::id>;
}
1
#
An object of type thread​::​id provides a unique identifier for each thread of execution and a single distinct value for all thread objects that do not represent a thread of execution ([thread.thread.class]).
Each thread of execution has an associated thread​::​id object that is not equal to the thread​::​id object of any other thread of execution and that is not equal to the thread​::​id object of any thread object that does not represent threads of execution.
2
#
thread​::​id is a trivially copyable class.
The library may reuse the value of a thread​::​id of a terminated thread that can no longer be joined.
3
#
[ Note
:
Relational operators allow thread​::​id objects to be used as keys in associative containers.
— end note
 ]
🔗
id() noexcept;
4
#
Effects: Constructs an object of type id.
5
#
Ensures: The constructed object does not represent a thread of execution.
🔗
bool operator==(thread::id x, thread::id y) noexcept;
6
#
Returns: true only if x and y represent the same thread of execution or neither x nor y represents a thread of execution.
🔗
bool operator!=(thread::id x, thread::id y) noexcept;
7
#
Returns: !(x == y)
🔗
bool operator<(thread::id x, thread::id y) noexcept;
8
#
Returns: A value such that operator< is a total ordering as described in [alg.sorting].
🔗
bool operator>(thread::id x, thread::id y) noexcept;
9
#
Returns: y < x.
🔗
bool operator<=(thread::id x, thread::id y) noexcept;
10
#
Returns: !(y < x).
🔗
bool operator>=(thread::id x, thread::id y) noexcept;
11
#
Returns: !(x < y).
🔗
template<class charT, class traits> basic_ostream<charT, traits>& operator<< (basic_ostream<charT, traits>& out, thread::id id);
12
#
Effects: Inserts an unspecified text representation of id into out.
For two objects of type thread​::​id x and y, if x == y the thread​::​id objects have the same text representation and if x != y the thread​::​id objects have distinct text representations.
13
#
Returns: out.
🔗
template<> struct hash<thread::id>;
14
#
The specialization is enabled ([unord.hash]).

30.3.2.2 thread constructors [thread.thread.constr]

🔗
thread() noexcept;
1
#
Effects: Constructs a thread object that does not represent a thread of execution.
2
#
Ensures: get_­id() == id().
🔗
template<class F, class... Args> explicit thread(F&& f, Args&&... args);
3
#
Requires:  F and each T in Args shall satisfy the Cpp17MoveConstructible requirements.
INVOKE(​DECAY_­COPY(​std​::​forward<F>(f)), DECAY_­COPY(​std​::​forward<Args>(​args))...) ([func.require]) shall be a valid expression.
4
#
Remarks: This constructor shall not participate in overload resolution if remove_­cvref_­t<F> is the same type as std​::​thread.
5
#
Effects:  Constructs an object of type thread.
The new thread of execution executes INVOKE(​DECAY_­COPY(​std​::​forward<F>(f)), DECAY_­COPY(​std​::​forward<Args>(​args))...) with the calls to DECAY_­COPY being evaluated in the constructing thread.
Any return value from this invocation is ignored.
[ Note
:
This implies that any exceptions not thrown from the invocation of the copy of f will be thrown in the constructing thread, not the new thread.
— end note
 ]
If the invocation of INVOKE(​DECAY_­COPY(​std​::​forward<F>(f)), DECAY_­COPY(​std​::​forward<Args>(args))...) terminates with an uncaught exception, terminate shall be called.
6
#
Synchronization: The completion of the invocation of the constructor synchronizes with the beginning of the invocation of the copy of f.
7
#
Ensures: get_­id() != id().
*this represents the newly started thread.
8
#
Throws: system_­error if unable to start the new thread.
9
#
Error conditions:
  • (9.1)
    resource_­unavailable_­try_­again — the system lacked the necessary resources to create another thread, or the system-imposed limit on the number of threads in a process would be exceeded.
🔗
thread(thread&& x) noexcept;
10
#
Effects: Constructs an object of type thread from x, and sets x to a default constructed state.
11
#
Ensures: x.get_­id() == id() and get_­id() returns the value of x.get_­id() prior to the start of construction.

30.3.2.3 thread destructor [thread.thread.destr]

🔗
~thread();
1
#
If joinable(), calls terminate().
Otherwise, has no effects.
[ Note
:
Either implicitly detaching or joining a joinable() thread in its destructor could result in difficult to debug correctness (for detach) or performance (for join) bugs encountered only when an exception is thrown.
Thus the programmer must ensure that the destructor is never executed while the thread is still joinable.
— end note
 ]

30.3.2.4 thread assignment [thread.thread.assign]

🔗
thread& operator=(thread&& x) noexcept;
1
#
Effects: If joinable(), calls terminate().
Otherwise, assigns the state of x to *this and sets x to a default constructed state.
2
#
Ensures: x.get_­id() == id() and get_­id() returns the value of x.get_­id() prior to the assignment.
3
#
Returns: *this.

30.3.2.5 thread members [thread.thread.member]

🔗
void swap(thread& x) noexcept;
1
#
Effects: Swaps the state of *this and x.
🔗
bool joinable() const noexcept;
2
#
Returns: get_­id() != id().
🔗
void join();
3
#
Effects:  Blocks until the thread represented by *this has completed.
4
#
Synchronization: The completion of the thread represented by *this synchronizes with the corresponding successful join() return.
[ Note
:
Operations on *this are not synchronized.
— end note
 ]
5
#
Ensures: The thread represented by *this has completed.
get_­id() == id().
6
#
Throws: system_­error when an exception is required ([thread.req.exception]).
7
#
Error conditions:
  • (7.1)
    resource_­deadlock_­would_­occur — if deadlock is detected or get_­id() == this_­thread​::​​get_­id().
  • (7.2)
    no_­such_­process — if the thread is not valid.
  • (7.3)
    invalid_­argument — if the thread is not joinable.
🔗
void detach();
8
#
Effects: The thread represented by *this continues execution without the calling thread blocking.
When detach() returns, *this no longer represents the possibly continuing thread of execution.
When the thread previously represented by *this ends execution, the implementation shall release any owned resources.
9
#
Ensures: get_­id() == id().
10
#
Throws: system_­error when an exception is required ([thread.req.exception]).
11
#
Error conditions:
  • (11.1)
    no_­such_­process — if the thread is not valid.
  • (11.2)
    invalid_­argument — if the thread is not joinable.
🔗
id get_id() const noexcept;
12
#
Returns: A default constructed id object if *this does not represent a thread, otherwise this_­thread​::​get_­id() for the thread of execution represented by *this.

30.3.2.6 thread static members [thread.thread.static]

🔗
unsigned hardware_concurrency() noexcept;
1
#
Returns: The number of hardware thread contexts.
[ Note
:
This value should only be considered to be a hint.
— end note
 ]
If this value is not computable or well-defined, an implementation should return 0.

30.3.2.7 thread specialized algorithms [thread.thread.algorithm]

🔗
void swap(thread& x, thread& y) noexcept;
1
#
Effects: As if by x.swap(y).

30.3.3 Namespace this_­thread [thread.thread.this]

namespace std::this_thread {
  thread::id get_id() noexcept;

  void yield() noexcept;
  template<class Clock, class Duration>
    void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
  template<class Rep, class Period>
    void sleep_for(const chrono::duration<Rep, Period>& rel_time);
}
🔗
thread::id this_thread::get_id() noexcept;
1
#
Returns: An object of type thread​::​id that uniquely identifies the current thread of execution.
No other thread of execution shall have this id and this thread of execution shall always have this id.
The object returned shall not compare equal to a default constructed thread​::​id.
🔗
void this_thread::yield() noexcept;
2
#
Effects: Offers the implementation the opportunity to reschedule.
3
#
Synchronization: None.
🔗
template<class Clock, class Duration> void sleep_until(const chrono::time_point<Clock, Duration>& abs_time);
4
#
Effects: Blocks the calling thread for the absolute timeout ([thread.req.timing]) specified by abs_­time.
5
#
Synchronization: None.
6
#
Throws: Timeout-related exceptions ([thread.req.timing]).
🔗
template<class Rep, class Period> void sleep_for(const chrono::duration<Rep, Period>& rel_time);
7
#
Effects: Blocks the calling thread for the relative timeout ([thread.req.timing]) specified by rel_­time.
8
#
Synchronization: None.
9
#
Throws: Timeout-related exceptions ([thread.req.timing]).