thread Class

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

Defines an object that's used to observe and manage a thread of execution within an application.

class thread;

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 is not 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. Therefore, 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.

Public Classes

NameDescription
thread::id ClassUniquely identifies the associated thread.

Public Constructors

NameDescription
thread::thread ConstructorConstructs a thread object.

Public Methods

NameDescription
thread::detach MethodDetaches the associated thread from the thread object.
thread::get_id MethodReturns the unique identifier of the associated thread.
thread::hardware_concurrency MethodStatic. Returns an estimate of the number of hardware thread contexts.
thread::join MethodBlocks until the associated thread completes.
thread::joinable MethodSpecifies whether the associated thread is joinable.
thread::native_handle MethodReturns the implementation-specific type that represents the thread handle.
thread::swap MethodSwaps the object state with a specified thread object.

Public Operators

NameDescription
thread::operator=Associates a thread with the current thread object.

Header: thread

Namespace: std

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 that's associated with the calling object is not joinable, the function throws a system_error that has an error code of invalid_argument.

If the thread that's associated with the calling object is invalid, the function throws a system_error that has an error code of no_such_process.

Returns a unique identifier for the associated thread.

id get_id() const noexcept;

Return Value

A thread::id object that uniquely identifies the associated thread, or thread::id() if no thread is associated with the object.

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 cannot be computed or is not well defined, this method returns 0.

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 does not compare equal to the thread::id object for any existing thread.

All default-constructed thread::id objects compare equal.

Blocks until the thread of execution that's 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 does not compare equal to the thread::id of any existing thread; if the call does not succeed, the value that's returned by get_id is unchanged.

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().

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 that's cast as void *.

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.

Swaps the object state with that of a specified thread object.

void swap(thread& Other) noexcept;

Parameters

Other
A thread object.

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 be executed by 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 that's returned by a call to get_id for the constructed object is thread::id().

The second constructor constructs an object that's associated with a new thread of execution and executes the pseudo-function INVOKE that's 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 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.

Header Files Reference
<thread>

Show: