<p>Taskflow provides template function that constructs a task to perform parallel iterations over a range of items.</p><sectionid="A1IndexBasedParallelFor"><h2><ahref="#A1IndexBasedParallelFor">Index-based Parallel Iterations</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 <ahref="classtf_1_1FlowBuilder.html#ab8417b211b18bb1e0f45a049331f084d" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each_index(B&& first, E&& last, S&& step, C&& callable)</a> represents parallel execution of the following loop:</p><preclass="m-code"><spanclass="c1">// positive step</span>
<spanclass="p">}</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="mi">100</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="p">[](</span><spanclass="kt">int</span><spanclass="n">i</span><spanclass="p">)</span><spanclass="p">{</span><spanclass="p">});</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="mi">0</span><spanclass="p">,</span><spanclass="mi">-2</span><spanclass="p">,</span><spanclass="p">[](</span><spanclass="kt">int</span><spanclass="n">i</span><spanclass="p">)</span><spanclass="p">{</span><spanclass="p">});</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: 77.062rem; height: 7.375rem;" viewBox="0.00 0.00 1232.51 117.54">
</div><p>The index types, <code>B</code>, <code>E</code>, and <code>S</code>, are templates to preserve the variable types and their underlying types must be of the same <em>integral</em> type (e.g., <code>int</code>, <code>size_t</code>, <code>unsigned</code>). By default, <ahref="classtf_1_1FlowBuilder.html#ab8417b211b18bb1e0f45a049331f084d" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each_index</a> creates a task that spawns a subflow (see <ahref="DynamicTasking.html" class="m-doc">Dynamic Tasking</a>) to run iterations in parallel. The subflow closure captures all input arguments through perfect forwarding to form a stateful closure such that any changes on the arguments will be visible to the execution context of the subflow. For example:</p><preclass="m-code"><spanclass="kt">int</span><spanclass="o">*</span><spanclass="n">vec</span><spanclass="p">;</span>
<spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="o"><<</span><spanclass="s">"parallel iteration on index "</span><spanclass="o"><<</span><spanclass="n">vec</span><spanclass="p">[</span><spanclass="n">i</span><spanclass="p">]</span><spanclass="o"><<</span><spanclass="sc">'\n'</span><spanclass="p">;</span>
<spanclass="p">}</span>
<spanclass="p">);</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></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. This property is especially important for task graph parallelism, because users can define end-to-end parallelism through stateful closures that marshal parameter exchange between dependent tasks.</p></section><sectionid="A1IteratorBasedParallelFor"><h2><ahref="#A1IteratorBasedParallelFor">Iterator-based Parallel Iterations</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 <ahref="classtf_1_1FlowBuilder.html#a564252001be679600b20ca9ed9920f6a" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each(B&& first, E&& last, C&& callable)</a> represents a parallel execution of the following loop:</p><preclass="m-code"><spanclass="k">for</span><spanclass="p">(</span><spanclass="k">auto</span><spanclass="n">i</span><spanclass="o">=</span><spanclass="n">first</span><spanclass="p">;</span><spanclass="n">i</span><spanclass="o"><</span><spanclass="n">last</span><spanclass="p">;</span><spanclass="n">i</span><spanclass="o">++</span><spanclass="p">)</span><spanclass="p">{</span>
<spanclass="p">}</span></pre><p>By default, <ahref="classtf_1_1FlowBuilder.html#a564252001be679600b20ca9ed9920f6a" class="m-doc">tf::<wbr/>Taskflow::<wbr/>for_each(B&& first, E&& last, C&& callable)</a> creates a task that spawns a subflow (see <ahref="DynamicTasking.html" class="m-doc">Dynamic Tasking</a>) that 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. This version of parallel-for applies to all iterable STL containers.</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="n">vec</span><spanclass="o">=</span><spanclass="p">{</span><spanclass="mi">1</span><spanclass="p">,</span><spanclass="mi">2</span><spanclass="p">,</span><spanclass="mi">3</span><spanclass="p">,</span><spanclass="mi">4</span><spanclass="p">,</span><spanclass="mi">5</span><spanclass="p">};</span>
<spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="o"><<</span><spanclass="s">"parallel for on item "</span><spanclass="o"><<</span><spanclass="n">i</span><spanclass="o"><<</span><spanclass="sc">'\n'</span><spanclass="p">;</span>
<spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="o"><<</span><spanclass="s">"parallel for on item "</span><spanclass="o"><<</span><spanclass="n">str</span><spanclass="o"><<</span><spanclass="sc">'\n'</span><spanclass="p">;</span>
<spanclass="p">});</span></pre><p>Similar to index-based parallel-for, the iterator types are templates to enable users to leverage the property of stateful closure. 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="n">vec</span><spanclass="p">;</span>
<spanclass="n">std</span><spanclass="o">::</span><spanclass="n">cout</span><spanclass="o"><<</span><spanclass="s">"parallel iteration on item "</span><spanclass="o"><<</span><spanclass="n">i</span><spanclass="o"><<</span><spanclass="sc">'\n'</span><spanclass="p">;</span>
<spanclass="p">});</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></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>
</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>