thread Class
Defines an object that's used to observe and manage a thread of execution within an application.
Syntax
class thread;
Remarks
You can use a thread object to observe and manage a thread of execution within an application. A thread object that's created by using the default constructor isn't associated with any thread of execution. A thread object that's constructed by using a callable object creates a new thread of execution and calls the callable object in that thread. Thread objects can be moved but not copied, which is why a thread of execution can be associated with only one thread object.
Every thread of execution has a unique identifier of type thread::id. The function this_thread::get_id returns the identifier of the calling thread. The member function thread::get_id returns the identifier of the thread that's managed by a thread object. For a default-constructed thread object, the thread::get_id method returns an object that has a value that's the same for all default-constructed thread objects and different from the value that's returned by this_thread::get_id for any thread of execution that could be joined at the time of the call.
Members
Public Classes
| Name | Description |
|---|---|
id |
Uniquely identifies the associated thread. |
Public Constructors
| Name | Description |
|---|---|
thread |
Constructs a thread object. |
Public Methods
| Name | Description |
|---|---|
detach |
Detaches the associated thread from the thread object. |
get_id |
Returns the unique identifier of the associated thread. |
hardware_concurrency |
Static. Returns an estimate of the number of hardware thread contexts. |
join |
Blocks until the associated thread completes. |
joinable |
Specifies whether the associated thread is joinable. |
native_handle |
Returns the implementation-specific type that represents the thread handle. |
swap |
Swaps the object state with a specified thread object. |
Public Operators
| Name | Description |
|---|---|
thread::operator= |
Associates a thread with the current thread object. |
Requirements
Header: <thread>
Namespace: std
detach
Detaches the associated thread. The operating system becomes responsible for releasing thread resources on termination.
void detach();
Remarks
After a call to detach, subsequent calls to get_id return id.
If the thread associated with the calling object isn't joinable, the function throws a system_error that has an error code of invalid_argument.
If the thread associated with the calling object is invalid, the function throws a system_error that has an error code of no_such_process.
get_id
Returns a unique identifier for the associated thread.
id get_id() const noexcept;
Return value
An id object that uniquely identifies the associated thread, or id() if no thread is associated with the object.
hardware_concurrency
Static method that returns an estimate of the number of hardware thread contexts.
static unsigned int hardware_concurrency() noexcept;
Return value
An estimate of the number of hardware thread contexts. If the value can't be computed or isn't well defined, this method returns 0.
Microsoft specific
hardware_concurrency returns the number of logical processors, which corresponds to the number of hardware threads that can execute simultaneously. It takes into account the number of physical processors, the number of cores in each physical processor, and simultaneous multithreading on each single core.
Before Windows 11 and Windows Server 2022, applications were limited by default to a single processor group, having at most 64 logical processors. This limited the number of concurrently executing threads to 64. For more information, see Processor Groups.
Starting with Windows 11 and Windows Server 2022, processes and their threads have processor affinities that by default span all processors in the system and across multiple groups on machines with more than 64 processors. The limit on the number of concurrent threads is now the total number of logical processors in the system.
id class
Provides a unique identifier for each thread of execution in the process.
class thread::id {
id() noexcept;
};
Remarks
The default constructor creates an object that doesn't compare equal to the thread::id object for any existing thread.
All default-constructed thread::id objects compare equal.
join
Blocks until the thread of execution associated with the calling object completes.
void join();
Remarks
If the call succeeds, subsequent calls to get_id for the calling object return a default thread::id that doesn't compare equal to the thread::id of any existing thread; if the call doesn't succeed, the value that's returned by get_id is unchanged.
joinable
Specifies whether the associated thread is joinable.
bool joinable() const noexcept;
Return value
true if the associated thread is joinable; otherwise, false.
Remarks
A thread object is joinable if get_id() != id().
native_handle
Returns the implementation-specific type that represents the thread handle. The thread handle can be used in implementation-specific ways.
native_handle_type native_handle();
Return value
native_handle_type is defined as a Win32 HANDLE cast as void *.
thread::operator=
Associates the thread of a specified object with the current object.
thread& operator=(thread&& Other) noexcept;
Parameters
Other
A thread object.
Return value
*this
Remarks
The method calls detach if the calling object is joinable.
After the association is made, Other is set to a default-constructed state.
swap
Swaps the object state with that of a specified thread object.
void swap(thread& Other) noexcept;
Parameters
Other
A thread object.
thread constructor
Constructs a thread object.
thread() noexcept;
template <class Fn, class... Args>
explicit thread(Fn&& F, Args&&... A);
thread(thread&& Other) noexcept;
Parameters
F
An application-defined function to execute on the thread.
A
A list of arguments to be passed to F.
Other
An existing thread object.
Remarks
The first constructor constructs an object that's not associated with a thread of execution. The value returned by get_id for the constructed object is thread::id().
The second constructor constructs an object that's associated with a new thread of execution. It executes the pseudo-function INVOKE defined in <functional>. If not enough resources are available to start a new thread, the function throws a system_error object that has an error code of resource_unavailable_try_again. If the call to F terminates with an uncaught exception, terminate is called. The call to F must not cause the thread to exit prematurely, such as by calling ExitThread or _endthreadex.
The third constructor constructs an object that's associated with the thread that's associated with Other. Other is then set to a default-constructed state.