taskflow-cpp/docs/ParallelIterations.html at master · baileyfu/taskflow-cpp

History

297 lines (287 loc) · 30.4 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

<!DOCTYPE html>

<head>

<title>Taskflow Algorithms » Parallel Iterations | Taskflow QuickStart</title>

</head>

<body>

<a href="https://taskflow.github.io"><img src="taskflow_logo.png" alt="" />Taskflow</a> | <a href="index.html" class="m-thin">QuickStart</a>

</svg></a>

</div>

<li><a href="pages.html">Handbook</a></li>

<li><a href="namespaces.html">Namespaces</a></li>

</ol>

<li><a href="annotated.html">Classes</a></li>

<li><a href="files.html">Files</a></li>

</svg></a></li>

</ol>

</div>

</nav></header>

<h1>

<a href="Algorithms.html">Taskflow Algorithms</a> »

Parallel Iterations

</h1>

<h3>Contents</h3>

<ul>

<li><a href="#A1IndexBasedParallelFor">Create an Index-based Parallel-Iteration Task</a></li>

<li><a href="#A1IteratorBasedParallelFor">Create an Iterator-based Parallel-Iteration Task</a></li>

</ul>

</nav>

Taskflow provides template functions for constructing tasks to perform parallel iterations over ranges of items.<section id="A1IndexBasedParallelFor"><h2><a href="#A1IndexBasedParallelFor">Create an Index-based Parallel-Iteration Task</a></h2>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 <a href="classtf_1_1FlowBuilder.html#a38ffe176bc3ae1827b9964322e3769d4" class="m-doc">tf::Taskflow::for_each_index(B first, E last, S step, C callable)</a> represents parallel execution of the following loop:<pre class="m-code">// positive step

for(auto i=first; i<last; i+=step) {

callable(i);

}

// negative step

for(auto i=first; i>last; i+=step) {

callable(i);

}</pre>We support only integer-based range. The range can go positive or negative direction.<pre class="m-code">taskflow.for_each_index(0, 100, 2, [](int i) { }); // 50 loops with a + step

taskflow.for_each_index(100, 0, -2, [](int i) { }); // 50 loops with a - step</pre>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:<div class="m-graph"><svg style="width: 77.062rem; height: 7.375rem;" viewBox="0.00 0.00 1232.51 117.54">

<title>Taskflow</title>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</g>

</svg>

</div>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 integral type (e.g., <code>int</code>, <code>size_t</code>, <code>unsigned</code>). By default, <a href="classtf_1_1FlowBuilder.html#a38ffe176bc3ae1827b9964322e3769d4" class="m-doc">tf::Taskflow::for_each_index</a> creates a task that spawns a subflow (see <a href="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:<pre class="m-code">int* vec;

int first, last;

auto init = taskflow.emplace([&](){

first = 0;

last = 1000;

vec = new int[1000];

});

auto pf = taskflow.for_each_index(std::ref(first), std::ref(last), 1,

[&] (int i) {

std::cout << "parallel iteration on index " << vec[i] << '\n';

}

);

// wrong! must use std::ref, or first and last are captured by copy

// auto pf = taskflow.for_each_index(first, last, 1, [&](int i) {

// std::cout << "parallel iteration on index " << vec[i] << '\n';

// });

init.precede(pf);</pre>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.</section><section id="A1IteratorBasedParallelFor"><h2><a href="#A1IteratorBasedParallelFor">Create an Iterator-based Parallel-Iteration Task</a></h2>Iterator-based parallel-for performs parallel iterations over a range specified by two <a href="https://en.cppreference.com/w/cpp/iterator/iterator">STL-styled iterators</a>, <code>first</code> and <code>last</code>. The task created by <a href="classtf_1_1FlowBuilder.html#ab405d7b10040530d8b04c11767b4960d" class="m-doc">tf::Taskflow::for_each(B first, E last, C callable)</a> represents a parallel execution of the following loop:<pre class="m-code">for(auto i=first; i<last; i++) {

callable(*i);

}</pre>By default, <a href="classtf_1_1FlowBuilder.html#ab405d7b10040530d8b04c11767b4960d" class="m-doc">tf::Taskflow::for_each(B first, E last, C callable)</a> creates a task that spawns a subflow (see <a href="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.<pre class="m-code">std::vector<int> vec = {1, 2, 3, 4, 5};

taskflow.for_each(vec.begin(), vec.end(), [](int i){

std::cout << "parallel for on item " << i << '\n';

});

std::list<std::string> list = {"hi", "from", "t", "a", "s", "k", "f", "low"};

taskflow.for_each(list.begin(), list.end(), [](const std::string& str){

std::cout << "parallel for on item " << str << '\n';

});</pre>Similar to index-based parallel-for, the iterator types are templates to enable users to leverage the property of stateful closure. For example:<pre class="m-code">std::vector<int> vec;

std::vector<int>::iterator first, last;;

tf::Task init = taskflow.emplace([&](){

vec.resize(1000);

first = vec.begin();

last = vec.end();

});

tf::Task pf = taskflow.for_each(std::ref(first), std::ref(last), [&](int i) {

std::cout << "parallel iteration on item " << i << '\n';

});

// wrong! must use std::ref, or first and last are captured by copy

// tf::Task pf = taskflow.for_each(first, last, [&](int i) {

// std::cout << "parallel iteration on item " <

// });

</div>

</article></main>

<div>Tab / T to search, Esc to close</div>

</div>

<form>

</form>

Search for symbols, directories, files, pages or

modules. You can omit any prefix from the symbol or file path; adding a

<code>:</code> or <code>/</code> suffix lists all members of given symbol or

directory.

Use ↓

/ ↑ to navigate through the list,

Enter to go.

Tab autocompletes common prefix, you can

copy a link to the result using ⌘

L while ⌘

M produces a Markdown link.

</div>

<div id="search-notfound" class="m-text m-warning m-text-center">Sorry, nothing was found.</div>

</div>

Taskflow handbook is part of the <a href="https://taskflow.github.io">Taskflow project</a>, copyright © <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>, 2018–2022. Generated by <a href="https://doxygen.org/">Doxygen</a> 1.8.14 and <a href="https://mcss.mosra.cz/">m.css</a>.

</div>

</nav></footer>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

ParallelIterations.html

Latest commit

History

ParallelIterations.html

File metadata and controls