Skip to content
Tutorials Center
My learning

Topics

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.

C++
#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

C++ Passing a policy to algorithms

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.

C++ Data races: what you must not do

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

C++
#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, partition and remove_if. std::accumulate, std::partial_sum and std::iota do not take a policy; use reduce, inclusive_scan and write the fill yourself. The std::ranges algorithms do not accept execution policies.
  • Use reduce, not accumulate. Parallel reduction reorders and regroups the operations, so the operation must be associative and (for reduce) 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 transform does) 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.