execution_policies.html

<cxx-clause id="parallel.execpol">
  <h1>Execution policies</h1>
  <cxx-section id="parallel.execpol.general">
    <h1>In general</h1>
      <p>This subclause describes classes that represent <dfn>execution policies</dfn>. An
      <dfn>execution policy</dfn> is an object that expresses the requirements on the ordering
      of functions invoked as a consequence of the invocation of a standard
      algorithm. Execution policies afford standard algorithms the discretion to
      execute in parallel.</p>

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

// standard sequential sort
<del>std::sort(vec.begin(), vec.end());</del>
<insdel>std::sort(std::begin(vec), std::end(vec));</insdel>
<ins2>std::sort(vec.begin(), vec.end());</ins2>

using namespace std::experimental::parallel<ins2>_v1</ins2>;

// explicitly sequential sort
<del>sort(seq, v.begin(), v.end());</del>
<insdel>sort(seq, std::begin(v), std::end(v));</insdel>
<ins2>sort(seq, v.begin(), v.end());</ins2>

// permitting parallel execution
<del>sort(par, v.begin(), v.end());</del>
<insdel>sort(par, std::begin(v), std::end(v));</insdel>
<ins2>sort(par, v.begin(), v.end());</ins2>

// permitting vectorization as well
<del>sort(vec, v.begin(), v.end());</del>
<insdel>sort(vec, std::begin(v), std::end(v));</insdel>
<ins2>sort(par_vec, v.begin(), v.end());</ins2>

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

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

<pre>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
  <cxx-ref insynopsis="" to="parallel.execpol.type"></cxx-ref>
  template&lt;class T&gt; struct is_execution_policy;

  <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.vec"></cxx-ref>
  class <del2>vector_execution_policy</del2><ins2>parallel_vector_execution_policy</ins2>;

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

<pre>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
  template&lt;class T&gt; struct is_execution_policy
    : integral_constant&lt;bool, <em>see below</em>&gt; { };
}
}
}
</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>If <code>T</code> is the type of a standard or implementation-defined execution policy, <code>is_execution_policy&lt;T&gt;</code> shall be publicly derived from <code>integral_constant&lt;bool,true&gt;</code>,
    otherwise from <code>integral_constant&lt;bool,false&gt;</code>.</p>
    
    <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>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
  class sequential_execution_policy{ <ins2><i>unspecified</i></ins2> };
}
}
}
</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>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
  class parallel_execution_policy{ <ins2><i>unspecified</i></ins2> };
}
}
}
</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.vec">
    <h1><ins2>Parallel+</ins2>Vector execution policy</h1>

<pre>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
  class <del2>vector_execution_policy</del2><ins2>parallel_vector_execution_policy</ins2>{ <ins2><i>unspecified</i></ins2> };
}
}
}
</pre>

    <p>The class <code>class <del2>vector_execution_policy</del2><ins2>parallel_vector_execution_policy</ins2></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.</p>

  </cxx-section>

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

<pre>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {

  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>
      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 dynamic 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 = ...
        
<ins>using namespace std::experimental::parallel<ins2>_v1</ins2>;</ins>
<del><code>std::</code></del>execution_policy exec = <del><code>std::</code></del>seq;

if(sort_me.size() &gt; threshold)
{
  exec = std::par;
}
 
<del>std::sort(exec, sort_me.begin(), sort_me.end());</del>
<ins>std::sort(exec, std::begin(sort_me), std::end(sort_me));</ins></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>

        <del>
          <cxx-requires>
            <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.
          </cxx-requires>
        </del>
        <ins>
          <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>
        </ins>
      </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>.

        <del>
          <cxx-requires>
            <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.
          </cxx-requires>
        </del>
        <insdel>
          <cxx-remarks>
            This operator shall not partipate in overload resolution unless
            <code>is_execution_policy&lt;T&gt;::value</code> is <code>true</code>.
          </cxx-remarks>
        </insdel>
      </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;
          template&lt;class T&gt; const T* get() <ins2>const</ins2> 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>

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

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

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

<pre>
namespace std {
namespace experimental {
namespace parallel<ins2>_v1</ins2> {
<del2>
  constexpr sequential_execution_policy seq = sequential_execution_policy();
  constexpr parallel_execution_policy   par = parallel_execution_policy();
  constexpr vector_execution_policy     vec = vector_execution_policy();
</del2>
<ins2>
  constexpr sequential_execution_policy      seq = {};
  constexpr parallel_execution_policy        par = {};
  constexpr parallel_vector_execution_policy par_vec = {};
</ins2>
}
}
}
</pre>

    <p>The header <code>&lt;<ins2>experimental/</ins2>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>