<li><ahref="#ParallelIterationsIncludeTheHeader">Include the Header</a></li>
<li><ahref="#A1IndexBasedParallelFor">Create an Index-based Parallel-Iteration Task</a></li>
<li><ahref="#ParallelForEachCaptureIndicesByReference">Capture Indices by Reference</a></li>
<li><ahref="#A1IteratorBasedParallelFor">Create an Iterator-based Parallel-Iteration Task</a></li>
<li><ahref="#ParallelForEachCaptureIteratorsByReference">Capture Iterators by Reference</a></li>
<li><ahref="#ParallelIterationsConfigureAPartitioner">Configure a Partitioner</a></li>
</ul>
</nav>
<p>Taskflow provides template functions for constructing tasks to perform parallel iterations over ranges of items.</p><sectionid="ParallelIterationsIncludeTheHeader"><h2><ahref="#ParallelIterationsIncludeTheHeader">Include the Header</a></h2><p>You need to include the header file, <code>taskflow/algorithm/for_each.hpp</code>, for using parallel-iteration algorithms.</p><preclass="m-code"><spanclass="cp">#include</span><spanclass="w"></span><spanclass="cpf"><taskflow/algorithm/for_each.hpp></span><spanclass="cp"></span></pre></section><sectionid="A1IndexBasedParallelFor"><h2><ahref="#A1IndexBasedParallelFor">Create an Index-based Parallel-Iteration Task</a></h2><p>Index-based parallel-for performs parallel iterations over a range <code>[first, last)</code> with the given <code>step</code> size. The task created by tf::Taskflow::for_each_index(B first, E last, S step, C callable, P&& part) represents parallel execution of the following loop:</p><preclass="m-code"><spanclass="c1">// positive step</span>
<spanclass="p">}</span><spanclass="w"></span></pre><p>We support only integer-based range. The range can go positive or negative direction.</p><preclass="m-code"><spanclass="n">taskflow</span><spanclass="p">.</span><spanclass="n">for_each_index</span><spanclass="p">(</span><spanclass="mi">0</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">100</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="w"></span><spanclass="p">[](</span><spanclass="kt">int</span><spanclass="w"></span><spanclass="n">i</span><spanclass="p">)</span><spanclass="w"></span><spanclass="p">{</span><spanclass="w"></span><spanclass="p">});</span><spanclass="w"></span><spanclass="c1">// 50 loops with a + step</span>
<spanclass="n">taskflow</span><spanclass="p">.</span><spanclass="n">for_each_index</span><spanclass="p">(</span><spanclass="mi">100</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">0</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">-2</span><spanclass="p">,</span><spanclass="w"></span><spanclass="p">[](</span><spanclass="kt">int</span><spanclass="w"></span><spanclass="n">i</span><spanclass="p">)</span><spanclass="w"></span><spanclass="p">{</span><spanclass="w"></span><spanclass="p">});</span><spanclass="w"></span><spanclass="c1">// 50 loops with a - step</span></pre><p>Notice that either positive or negative direction is defined in terms of the range, <code>[first, last)</code>, where <code>end</code> is excluded. In the positive case, the 50 items are 0, 2, 4, 6, 8, ..., 96, 98. In the negative case, the 50 items are 100, 98, 96, 04, ... 4, 2. An example of the Taskflow graph for the positive case under 12 workers is depicted below:</p><divclass="m-graph"><svgstyle="width: 86.300rem; height: 11.600rem;" viewBox="0.00 0.00 863.43 116.00">
</div></section><sectionid="ParallelForEachCaptureIndicesByReference"><h2><ahref="#ParallelForEachCaptureIndicesByReference">Capture Indices by Reference</a></h2><p>You can pass indices by reference using <ahref="https://en.cppreference.com/w/cpp/utility/functional/ref">std::<wbr/>ref</a> to marshal parameter update between dependent tasks. This is especially useful when the range indices are unknown at the time of creating a for-each-index task, but is initialized from another task.</p><preclass="m-code"><spanclass="kt">int</span><spanclass="o">*</span><spanclass="w"></span><spanclass="n">vec</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel iteration on index "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">vec</span><spanclass="p">[</span><spanclass="n">i</span><spanclass="p">]</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="c1">// wrong! must use std::ref, or first and last are captured by copy</span>
<spanclass="c1">// auto pf = taskflow.for_each_index(first, last, 1, [&](int i) {</span>
<spanclass="c1">// std::cout << "parallel iteration on index " << vec[i] << '\n';</span>
<spanclass="c1">// });</span>
<spanclass="n">init</span><spanclass="p">.</span><spanclass="n">precede</span><spanclass="p">(</span><spanclass="n">pf</span><spanclass="p">);</span><spanclass="w"></span></pre><p>When <code>init</code> finishes, the parallel-for task <code>pf</code> will see <code>first</code> as 0 and <code>last</code> as 1000 and performs parallel iterations over the 1000 items.</p></section><sectionid="A1IteratorBasedParallelFor"><h2><ahref="#A1IteratorBasedParallelFor">Create an Iterator-based Parallel-Iteration Task</a></h2><p>Iterator-based parallel-for performs parallel iterations over a range specified by two <ahref="https://en.cppreference.com/w/cpp/iterator/iterator">STL-styled iterators</a>, <code>first</code> and <code>last</code>. The task created by tf::Taskflow::for_each(B first, E last, C callable, P&& part) represents a parallel execution of the following loop:</p><preclass="m-code"><spanclass="k">for</span><spanclass="p">(</span><spanclass="k">auto</span><spanclass="w"></span><spanclass="n">i</span><spanclass="o">=</span><spanclass="n">first</span><spanclass="p">;</span><spanclass="w"></span><spanclass="n">i</span><spanclass="o"><</span><spanclass="n">last</span><spanclass="p">;</span><spanclass="w"></span><spanclass="n">i</span><spanclass="o">++</span><spanclass="p">)</span><spanclass="w"></span><spanclass="p">{</span><spanclass="w"></span>
<spanclass="p">}</span><spanclass="w"></span></pre><p>tf::Taskflow::for_each(B first, E last, C callable, P&& part) simultaneously applies the callable to the object obtained by dereferencing every iterator in the range <code>[first, last)</code>. It is user's responsibility for ensuring the range is valid within the execution of the parallel-for task. Iterators must have the post-increment operator ++ defined.</p><preclass="m-code"><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">vector</span><spanclass="o"><</span><spanclass="kt">int</span><spanclass="o">></span><spanclass="w"></span><spanclass="n">vec</span><spanclass="w"></span><spanclass="o">=</span><spanclass="w"></span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">3</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">4</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">5</span><spanclass="p">};</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel for on item "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">i</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel for on item "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">str</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="p">});</span><spanclass="w"></span></pre></section><sectionid="ParallelForEachCaptureIteratorsByReference"><h2><ahref="#ParallelForEachCaptureIteratorsByReference">Capture Iterators by Reference</a></h2><p>Similar to <ahref="classtf_1_1FlowBuilder.html#a3b132bd902331a11b04b4ad66cf8bf77" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each_index</a>, iterators of <ahref="classtf_1_1FlowBuilder.html#aae3edfa278baa75b08414e083c14c836" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each</a> are templated to allow capturing range parameters by reference, such that one task can set up the range before another task performs the parallel-for algorithm. For example:</p><preclass="m-code"><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">vector</span><spanclass="o"><</span><spanclass="kt">int</span><spanclass="o">></span><spanclass="w"></span><spanclass="n">vec</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel iteration on item "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">i</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="p">});</span><spanclass="w"></span>
<spanclass="c1">// wrong! must use std::ref, or first and last are captured by copy</span>
<spanclass="c1">// tf::Task pf = taskflow.for_each(first, last, [&](int i) {</span>
<spanclass="c1">// std::cout << "parallel iteration on item " << i << '\n';</span>
<spanclass="c1">// });</span>
<spanclass="n">init</span><spanclass="p">.</span><spanclass="n">precede</span><spanclass="p">(</span><spanclass="n">pf</span><spanclass="p">);</span><spanclass="w"></span></pre><p>When <code>init</code> finishes, the parallel-for task <code>pf</code> will see <code>first</code> pointing to the beginning of <code>vec</code> and <code>last</code> pointing to the end of <code>vec</code> and performs parallel iterations over the 1000 items. The two tasks form an end-to-end task graph where the parameters of parallel-for are computed on the fly.</p></section><sectionid="ParallelIterationsConfigureAPartitioner"><h2><ahref="#ParallelIterationsConfigureAPartitioner">Configure a Partitioner</a></h2><p>You can configure a partitioner for parallel-iteration tasks to run with different scheduling methods, such as guided partitioning, dynamic partitioning, and static partitioning. The following example creates two parallel-iteration tasks using two different partitioners, one with the static partitioning algorithm and another one with the guided partitioning algorithm:</p><preclass="m-code"><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">vector</span><spanclass="o"><</span><spanclass="kt">int</span><spanclass="o">></span><spanclass="w"></span><spanclass="n">vec</span><spanclass="p">(</span><spanclass="mi">1024</span><spanclass="p">,</span><spanclass="w"></span><spanclass="mi">0</span><spanclass="p">);</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel iteration on item "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">i</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="w"></span><spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="s">"parallel iteration on item "</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="n">i</span><spanclass="w"></span><spanclass="o"><<</span><spanclass="w"></span><spanclass="sc">'\n'</span><spanclass="p">;</span><spanclass="w"></span>
<spanclass="p">);</span><spanclass="w"></span></pre><asideclass="m-note m-info"><h4>Note</h4><p>By default, parallel-iteration tasks use <ahref="namespacetf.html#a66b72776c788898aee9e132b0ea9b405" class="m-doc">tf::<wbr/>DefaultPartitioner</a> if no partitioner is specified.</p></aside></section>
</div>
</div>
</div>
</article></main>
<divclass="m-doc-search" id="search">
<ahref="#!" onclick="return hideSearch()"></a>
<divclass="m-container">
<divclass="m-row">
<divclass="m-col-m-8 m-push-m-2">
<divclass="m-doc-search-header m-text m-small">
<div><spanclass="m-label m-default">Tab</span> / <spanclass="m-label m-default">T</span> to search, <spanclass="m-label m-default">Esc</span> to close</div>