execution_policies.html

<cxx-clause id="parallel.execpol">
  <h1>Execution policies</h1>
  <cxx-section id="parallel.execpol.general">
    <h1>In general</h1>
      <p>
        This clause describes classes that are <dfn>execution policy</dfn> types. An object
        of an execution policy type indicates the kinds of parallelism allowed in the execution
        of an algorithm and expresses the consequent requirements on the element
        access functions.
      </p>

      <cxx-example>
    <pre>std::vector&lt;int&gt; v = ...

// standard sequential sort
std::sort(v.begin(), v.end());

using namespace std::experimental::parallel;

// explicitly sequential sort
sort(seq, v.begin(), v.end());

// permitting parallel execution
sort(par, v.begin(), v.end());

// permitting vectorization as well
sort(par_vec, v.begin(), v.end());

// sort with dynamically-selected execution
size_t threshold = ...
execution_policy exec = seq;
if (v.size() &gt; threshold)
{
  exec = par;
}

sort(exec, v.begin(), v.end());
</pre>
    </cxx-example><pre>
</pre> 
    <cxx-note>
      Because different parallel architectures may require idiosyncratic
      parameters for efficient execution, implementations of the Standard Library 
      may provide additional execution policies to those described in this
      Technical Specification as extensions.
    </cxx-note>
  </cxx-section>
  <cxx-section id="parallel.execpol.synopsis">
  <h1>Header <code>&lt;experimental/execution_policy&gt;</code> synopsis</h1>

<pre>
namespace std {
namespace experimental {
namespace parallel {
inline namespace v2 {
  <cxx-ref insynopsis="" to="parallel.execpol.type"></cxx-ref>
  template&lt;class T&gt; struct is_execution_policy;
  template&lt;class T&gt; constexpr bool is_execution_policy_v = is_execution_policy&lt;T&gt;::value;

  <cxx-ref insynopsis="" to="parallel.execpol.seq"></cxx-ref>
  class sequential_execution_policy;

  <cxx-ref insynopsis="" to="parallel.execpol.par"></cxx-ref>
  class parallel_execution_policy;

  <cxx-ref insynopsis="" to="parallel.execpol.parvec"></cxx-ref>
  class parallel_vector_execution_policy;

  <cxx-ref insynopsis="" to="parallel.execpol.dynamic"></cxx-ref>
  class execution_policy;

<ins>namespace execution {
  <cxx-ref insynopsis="" to="parallel.execpol.unseq"></cxx-ref>
  <ins>class unsequenced_policy;</ins>

  <cxx-ref insynopsis="" to="parallel.execpol.vec"></cxx-ref>
  <ins>class vector_policy;</ins>
}</ins>
}
}
}
</pre>
  </cxx-section>
  <cxx-section id="parallel.execpol.type">
    <h1>Execution policy type trait</h1>

<pre>
template&lt;class T&gt; struct is_execution_policy { <em>see below</em> };
</pre>

    <p><code>is_execution_policy</code> can be used to detect parallel execution policies for the purpose of excluding function signatures from otherwise ambiguous overload resolution participation.</p>
    
    <p><code>is_execution_policy&lt;T&gt;</code> shall be a UnaryTypeTrait with a BaseCharacteristic of <code>true_type</code> if <code>T</code> is the type of a standard or implementation-defined execution policy, otherwise <code>false_type</code>.

    <pre>
</pre>

    <cxx-note>
      This provision reserves the privilege of creating non-standard execution policies to the library implementation.
    </cxx-note>
    
    <p>The behavior of a program that adds specializations for <code>is_execution_policy</code> is undefined.</p>
  </cxx-section>

  <cxx-section id="parallel.execpol.seq">
    <h1>Sequential execution policy</h1>

    <pre>
class sequential_execution_policy{ <i>unspecified</i> };
</pre>

    <p>The class <code>sequential_execution_policy</code> is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and require that a parallel algorithm's execution may not be parallelized.</p>

  </cxx-section>
  <cxx-section id="parallel.execpol.par">
    <h1>Parallel execution policy</h1>

<pre>
class parallel_execution_policy{ <i>unspecified</i> };
</pre>

    <p>The class <code>parallel_execution_policy</code> is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be parallelized.</p>

  </cxx-section>
  <cxx-section id="parallel.execpol.parvec">
    <h1>Parallel+Vector execution policy</h1>

<pre>
class parallel_vector_execution_policy{ <i>unspecified</i> };
</pre>

    <p>The class <code>class parallel_vector_execution_policy</code> is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be vectorized and parallelized.</p>

  </cxx-section>

  <cxx-section id="parallel.execpol.unseq">
    <h1>Unsequenced execution policy</h1>
<ins>

<pre>
class unsequenced_policy{ <i>unspecified</i> };
</pre>

    <p>The class <code>unsequenced_policy</code> is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be vectorized, e.g., executed on a single thread using instructions that operate on multiple data items.</p>

</ins>
  </cxx-section>

  <cxx-section id="parallel.execpol.vec">
    <h1>Vector execution policy</h1>
<ins>

<pre>
class vector_policy{ <i>unspecified</i> };
</pre>

    <p>The class <code>vector_policy</code> is an execution policy type used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be vectorized. Additionally, such vectorization will result in an execution that respects the sequencing constraints of wavefront application ([parallel.alg.general.wavefront]). <cxx-note>The implementation thus makes stronger guarantees than for <code>unsequenced_policy</code>, for example.</cxx-note></p>

</ins>
  </cxx-section>

  <cxx-section id="parallel.execpol.dynamic">
    <h1>Dynamic execution policy</h1>

<pre>
class execution_policy
{
  public:
    <cxx-ref insynopsis="" to="parallel.execpol.con"></cxx-ref>
    template&lt;class T&gt; execution_policy(const T&amp; exec);
    template&lt;class T&gt; execution_policy&amp; operator=(const T&amp; exec);

    <cxx-ref insynopsis="" to="parallel.execpol.access"></cxx-ref>
    const type_info&amp; type() const noexcept;
    template&lt;class T&gt; T* get() noexcept;
    template&lt;class T&gt; const T* get() const noexcept;
};
</pre>

    <p>The class <code>execution_policy</code> is a container for execution policy objects.
    <code>execution_policy</code> allows dynamic control over standard algorithm execution.</p>

    <cxx-example>
      <pre>std::vector&lt;float&gt; sort_me = ...
        
using namespace std::experimental::parallel;
execution_policy exec = seq;

if(sort_me.size() &gt; threshold)
{
  exec = std::par;
}
 
std::sort(exec, std::begin(sort_me), std::end(sort_me));</pre>
    </cxx-example>

    <p>Objects of type <code>execution_policy</code> shall be constructible and assignable from objects of
    type <code>T</code> for which <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.</p>

    <cxx-section id="parallel.execpol.con">
      <h1><code>execution_policy</code> construct/assign</h1>

      <cxx-function>
        <cxx-signature>template&lt;class T&gt; execution_policy(const T&amp; exec);</cxx-signature>

        <cxx-effects>Constructs an <code>execution_policy</code> object with a copy of <code>exec</code>'s state.</cxx-effects>

        <cxx-remarks>
          This constructor shall not participate in overload resolution unless
          <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.
        </cxx-remarks>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template&lt;class T&gt; execution_policy&amp; operator=(const T&amp; exec);</cxx-signature>

        <cxx-effects>Assigns a copy of <code>exec</code>'s state to <code>*this</code>.</cxx-effects>

        <cxx-returns><code>*this</code>.
      </cxx-function>
    </cxx-section>

    <cxx-section id="parallel.execpol.access">
      <h1><code>execution_policy</code> object access</h1>

      <cxx-function>
        <cxx-signature>const type_info&amp; type() const noexcept;</cxx-signature>

        <cxx-returns><code>typeid(T)</code>, such that <code>T</code> is the type of the execution policy object contained by <code>*this</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
      <cxx-signature>template&lt;class T&gt; T* get() noexcept;</cxx-signature>
      <cxx-signature>template&lt;class T&gt; const T* get() const noexcept;</cxx-signature>

        <cxx-returns>If <code>target_type() == typeid(T)</code>, a pointer to the stored execution policy object; otherwise a null pointer.</cxx-returns>

        <cxx-requires>
          <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.
        </cxx-requires>
      </cxx-function>

    </cxx-section>
  </cxx-section>

  <cxx-section id="parallel.execpol.objects">
    <h1>Execution policy objects</h1>

<pre>
constexpr sequential_execution_policy      seq{};
constexpr parallel_execution_policy        par{};
constexpr parallel_vector_execution_policy par_vec{};
</pre>

    <p>The header <code>&lt;experimental/execution_policy&gt;</code> declares a global object associated with each type of execution policy defined by this Technical Specification.</p>
  </cxx-section>
</cxx-clause>