To run any function pointer, functor, or lambda expression in a new thread of execution, pass it to the constructor of std::thread, along with any number of arguments. For example, these two lines are equivalent:

The function with its arguments is called in a newly launched thread of execution prior to returning from the thread’s constructor .

Both the function and its arguments must first be copied or moved (for example, for temporary objects or if std::move() is used) to memory accessible to this new thread. Therefore, to pass a reference as an argument, you first have to make it copyable: for example, by wrapping it using std::ref() / std::cref(). Of course, you can also simply use a lambda expression with capture-by-reference. Functors, reference wrappers, and lambda expressions are all discussed in detail in Chapter 2.

The thread class does not offer any facilities to retrieve the function’s result. On the contrary, its return value is ignored, and std::terminate() is called if it raises an uncaught exception (which by default terminates the process: see Chapter 8). Retrieving function results is made easier though using the constructs defined in the <future> header, as detailed later in this chapter.

A std::thread is said to be joinable if it is associated with a thread of execution. This property is queried using joinable(). threads initialized with a function start out joinable, whereas default-constructed ones start out non-joinable. After that, thread instances can be moved and swapped as expected. Copying thread objects, however, is not possible. This ensures that at all times, at most one thread instance represents a given thread of execution. A handle to the underlying native thread representation may be obtained through the optional native_handle() member.

The two most important facts to remember about std::threads are as follows:

So, to make sure the latter does not happen, always make sure to eventually call one of the following functions on each joinable thread:

A std::thread offers no means to terminate, interrupt, or resume the underlying thread of execution. Stopping the thread function or otherwise synchronizing with it must therefore be accomplished using other means, such as mutexes or condition variables, both discussed later in this chapter.

Each active thread has a unique thread::id, which offers all operations you typically need for thread identifiers:

If a std::thread object is joinable, you can call get_id() on it to obtain the identifier of the associated thread. All non-joinable threads have an identifier that equals the default-constructed thread::id. To get the identifier for the currently active thread, you can also call the global std::this_thread::get_id() function.

The static std::thread::hardware_concurrency() function returns the number of concurrent threads (or an approximation thereof) supported by the current hardware, or zero if this cannot be determined. This number may be larger than the number of physical cores: if the hardware, for instance, supports simultaneous multithreading (branded by Intel as Hyper-Threading), this will be an even multiple of (typically twice) the number of cores.

In addition to get_id(), the std::this_thread namespace contains three additional functions to manipulate the current thread of execution:

Unless noted here, all functions in <thread> are declared noexcept. Several std::thread members call native system functions to manipulate native threads. If those fail, a std:: system_error is thrown with one of the following error codes (see Chapter 8 for more information on system_errors and error codes):

Failure to allocate storage in the constructor may also be reported by throwing an instance of std::bad_ alloc or a class that derives from bad_alloc.

All return objects have a synchronous get() function that blocks until the associated shared state is ready and then either returns the provided value (may be void) or rethrows the provided exception in the calling thread.

To wait until the result is ready without actually retrieving it, use one of the wait functions: wait(), wait_until(time_point), or wait_for(duration). The former waits indefinitely, and the latter two wait no longer than a timeout specified using one of the types defined in <chrono> (Chapter 2).

A return object that is associated with a shared state is said to be valid. Validity may be checked using valid(). A valid future cannot be constructed directly but must always be obtained from the shared state’s single provider.

There are two important limitations with std::futures:

A shared_future is completely equivalent to a future, but without these two limitations: that is, they can be copied, and get() may be called more than once. A shared_future is obtained by calling share() on a future. This can again be done only once, because it invalidates the future. But once you have a shared_future, more can be created by copying it. Here is an overview:

The <future> library offers three different providers: std::async(), packaged_tasks, and promises. This section discusses each in turn. As example workload for asynchronous computations, we use the following greatest-common-divisor function:

Most functions in the <future> header throw an exception if misused. Because the behavior is consistent across all provider and return objects, this single section provides the overview. The following discussion refers to standard exception classes as well as the concepts of error codes and categories , all of which are explained in detail in Chapter 8.

As usual, default and move constructors, move-assignment operators, and swap() functions are declared noexcept, and of course destructors never throw exceptions either. Apart from these, only the valid() functions are noexcept.

Most other member functions of provider and return objects throw a std::future_error in case of an error, a subclass of std::logic_error. More similar to a std::system_error, though, a future_error also has a code() member that returns an std::error_code, in this case one for which the category() equals std::future_category() (whose name() equals "future"). For future_errors, the value() of the error_code always equals one of the four values of the error code enum class std::future_ errc :

When using an async launch policy, async() may throw a system_error with error code resource_unavailable_try_again if it fails to create a new thread.

Basic usage of a std::mutex object m is as follows:

The lock() function blocks until the thread has acquired ownership of a mutex. For a basic std::mutex object, only a single thread is granted exclusive ownership at any given time. The intention is that only threads that own a given mutex are allowed to access the resources guarded by it, thus preventing data races. A thread retains this ownership until it releases it by calling unlock(). Upon unlocking, another thread that is blocked on the mutex, if any, is woken up and granted ownership. The order in which threads are woken up is undefined.

It is critical that any and all successful calls to a lock function are paired with a call to unlock(). To ensure this is done in a consistent and exception-safe manner, you should avoid calling these lock and unlock functions directly and use the Resource Acquisition Is Initialization (RAII) idiom instead. For this, the Standard Library offers several lock classes. The simplest, leanest lock is lock_guard, which simply calls lock() in its constructor and unlock() in its destructor:

The Standard Library offers several flavors of mutexes, each with additional capabilities compared to the basic std::mutex. More restricted mutex types can typically be implemented more efficiently.

There are three lock types provided by the standard: std::lock_guard, unique_lock, and shared_lock.

As soon as threads need to acquire ownership of multiple mutexes at the same time, the risk of deadlocks becomes imminent. Different techniques may be employed to prevent such deadlocks: for example, locking the mutexes in all threads in the same order (error-prone), or so-called try-and-back-off schemes. The Standard Library offers templated helper functions instead to facilitate this:

This function blocks until ownership is acquired for all lockable objects passed to it. These can be mutexes (which, after locking, you should transfer to RAII locks using their adopt_lock constructors), but also unique_ or shared_locks (for example, constructed with defer_lock). Although the standard does not specify how this should be achieved, if all threads use std::lock(), there are no deadlocks.

Of course, a nonblocking std::try_lock() equivalent of std::lock() exists as well. It calls try_lock() on all objects in the order they are passed and returns the 0-based index of the first try_lock() that fails, or -1 if they all succeed. If it fails to lock an object, any objects that were locked already are unlocked again first.

Using a mutex before it is fully constructed or after it has been destructed results in undefined behavior. If used properly, only the functions mentioned next may throw an exception.

For mutexes, all lock() and lock_shared() functions (not the try_ variants) may throw a system_error with one of these error codes (see Chapter 8):

By extension, both std::lock() and the constructors and locking functions of RAII locks may throw the same exceptions as well. Any of the RAII locking functions (including the try_ variants) are guaranteed to throw a system_error with resource_deadlock_would_occur if owns_lock() == true (even if the underlying mutex is recursive), and their unlock() members will throw one with operation_not_permitted if owns_lock() == false.

If any locking function throws an exception, it is guaranteed that no mutex was locked.

std::call_once() is a thread-safe utility function to ensure other functions are called at most once. This is useful, for example, for implementing the lazy initialization idiom:

Only a single thread that calls call_once() with a given instance of std::once_flag—a default-constructible, non-copyable, non-moveable helper class—effectively executes the function passed alongside it. Any subsequent calls have no effect. If multiple threads concurrently call call_once() with the same flag, all but one is suspended until the one executing the function has finished doing so. Recursively calling call_once() with the same flag results in undefined behavior.

Any return value of the function is ignored. If running the function throws an exception, this is thrown in the calling thread, and another thread is allowed to execute with the flag again. If there are threads blocked, one of them is woken up.

Suppose the following variables are somehow shared between threads:

Then the archetypal pattern for waiting until ready becomes true is

To wait using a condition_variable, a thread must first lock the corresponding mutex using a std::unique_lock<std::mutex>.³ As wait() blocks the thread, it also unlocks the mutex: this allows other threads to lock the mutex in order to satisfy the shared condition. When a waiting thread is woken up, before returning from wait(), it always first locks the mutex again using the unique_lock, making it safe to recheck the condition.

Alternatively, all wait functions have an overload that takes a predicate function as an argument: any function or functor that returns a value that can be evaluated as a Boolean may be used. The loop in the example, for instance, is equivalent to

There are two sets of additional wait functions that never block longer than a given timeout: wait_until(time_point) and wait_for(duration) . The timeouts are, as always, expressed using types defined in the <chrono> header. The return value of wait_until() and wait_for() is as follows:

Two notification functions are provided: notify_all(), which unblocks all threads waiting on a condition variable, and notify_one(), which unblocks only a single thread. The order in which multiple waiting threads are woken up is unspecified.

Notification normally occurs because the condition has changed:

Note that the notifying thread is not required to own the mutex when calling a notification function. In fact, the first thing any unblocked thread does is attempt to lock the mutex, so releasing ownership prior to notification may actually improve performance.⁴

There is one more notification function, but it is a nonmember function and has the following signature:

The constructor of a condition variable may throw a std::bad_alloc if insufficient memory is available, or a std::system_error with resource_unavailable_try_again as an error code if the condition variable cannot be created due to a non-memory-related resource limitation.

Destructing a condition variable upon which a thread is still waiting results in undefined behavior.

Variables of the std::atomic<T> type mostly behave like regular T variables—thanks to the obvious constructors and assignment and cast operators—offering a restricted set of fine-grained atomic operations with specific memory-consistency properties. More details follow shortly, but first we introduce the template specializations of atomic<T>.

The std::atomic_ flag is a simple, guaranteed lock-free, atomic, Boolean-like type. It can only be default constructed and cannot be copied, moved, or swapped. It is not specified whether the default constructor initializes the flag. The only initialization that is guaranteed to work is this exact expression:

An atomic_flag offers only two other members:

Both functions have synchronization properties similar to atomic_bools and again accept an optional std::memory_order parameter as well.

For compatibility with C, <atomic> defines nonmember counterparts for all member functions of std::atomic<T> and std::atomic_flag: atomic_init(), atomic_load(), atomic_fetch_add(), atomic_flag_test_and_set(), and so on. As a C++ programmer, you normally never need any of these: simply use the classes’ member functions.

The <atomic> header also provides two functions to explicitly create acquire and/or release fences: std::atomic_thread_fence() and std::atomic_signal_fence() . The concept of fences is as explained earlier this chapter. Both take a std::memory_order argument to specify the desired fence type: memory_order_release for a release fence, either memory_order_acquire or memory_order_consume for an acquire fence, and memory_order_acq_rel and memory_order_seq_cst for fences that are both acquire and release fences, with the latter option denoting the fence has to be the sequentially consistent variant (the difference in their semantics falls outside the scope of this book). A fence with memory_order_relaxed has no effect.

The difference between the two functions is that the latter only restrict reorderings between a thread and a signal handler executed in the same thread. The latter only constrains the compiler but does not inject any instructions to constrain the hardware (memory caches and CPU).