C++ Reference ยท Algorithms
C++ execution policies for parallel algorithms
How C++17 execution policies work: std::execution::seq, par, par_unseq and unseq, which algorithms accept them, data-race rules, exceptions and GCC/TBB notes.
Since C++17 most algorithms in <algorithm> and <numeric> have an extra overload whose first argument is an execution policy. The policy tells the library that you allow it to run the algorithm in parallel, vectorized, or both. You write the same algorithm call and add one argument; the library decides how many threads to use.
The policies live in the header <execution>, namespace std::execution. This page explains what each policy promises, what your code must guarantee in return, and what to expect from GCC.
#include <execution> std::sort(std::execution::par, v.begin(), v.end()); auto sum = std::reduce(std::execution::par_unseq, v.begin(), v.end(), 0L);
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with std::cin or std::getline), it gets the next line from this box.
Syntax
#include <execution> std::execution::sequenced_policy std::execution::seq; std::execution::parallel_policy std::execution::par; std::execution::parallel_unsequenced_policy std::execution::par_unseq; std::execution::unsequenced_policy std::execution::unseq; // C++20 template<class ExecutionPolicy, class It> void std::sort(ExecutionPolicy&& policy, It first, It last);
| Policy | Meaning |
|---|---|
seq |
No parallelism. Runs on the calling thread, in an unspecified but non-interleaved order. |
par |
May run on several threads. Calls to your callable on different elements may overlap in time, but each call runs on one thread from start to finish. |
par_unseq |
May use several threads and SIMD: calls can be interleaved on the same thread. |
unseq |
C++20. Vectorization on the calling thread only. |
Returns: the same thing as the overload without a policy.
Errors / undefined behavior: a data race between calls is undefined behavior. With par_unseq and unseq the callable must also not take locks or allocate memory in ways that can block, because two calls may interleave on one thread (a mutex locked in one call and waited on by another can deadlock). If a callable throws an exception under any policy, even seq, std::terminate is called instead of the exception reaching your code. (Memory allocation failure inside the algorithm itself can still throw std::bad_alloc.)
Usage notes
- Iterators. Policy overloads need at least forward iterators. Input iterators are not allowed, so you cannot use a policy with
std::istream_iterator. - Which algorithms. About 70 algorithms accept a policy, among them
sort,stable_sort,transform,for_each,find,count,copy,fill,all_of,reduce,transform_reduce,inclusive_scan,exclusive_scan,merge,partitionandremove_if.std::accumulate,std::partial_sumandstd::iotado not take a policy; usereduce,inclusive_scanand write the fill yourself. Thestd::rangesalgorithms do not accept execution policies. - Use
reduce, notaccumulate. Parallel reduction reorders and regroups the operations, so the operation must be associative and (forreduce) commutative. Floating-point addition is not truly associative, so a parallel float sum can differ slightly between runs. - Only large inputs benefit. Starting threads and splitting work costs time. For a few thousand cheap elements a parallel call is often slower than the serial one. Measure before you add a policy.
- Elements can be accessed from several threads. Writing to different elements (as
transformdoes) is fine. Writing to the same object is not. - GCC and TBB. GCC implements parallel algorithms with Intel's oneTBB. If TBB is installed, link it with
-ltbb; if the compiler cannot find TBB headers, the library falls back to running everything serially, so the code still builds and gives correct results. Our runner has one CPU and no TBB, so these examples show correct results but no speed-up. MSVC and libc++ handle this differently, so check your toolchain's documentation for the link step. - Custom policies.
std::is_execution_policy_v<T>tells you whether a type is a policy, which is useful when you write your own algorithm templates.