taskflow/docs/ExecuteTaskflow.html at master · yhcpp/taskflow · GitHub

History

292 lines (259 loc) · 43.2 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

<!DOCTYPE html>

<head>

<title>Cookbook » Executor | 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="Cookbook.html">Cookbook</a> »

Executor

</h1>

<h3>Contents</h3>

<ul>

<li><a href="#CreateAnExecutor">Create an Executor</a></li>

<li><a href="#ExecuteATaskflow">Execute a Taskflow</a></li>

<li><a href="#ExecuteATaskflowWithTransferredOwnership">Execute a Taskflow with Transferred Ownership</a></li>

<li><a href="#ThreadSafety">Touch an Executor from Multiple Threads</a></li>

<li><a href="#QueryTheWorkerID">Query the Worker Identieir</a></li>

<li><a href="#ObserveThreadActivities">Observe Thread Activities</a></li>

</ul>

</div>

After you create a task dependency graph, you need to submit it to threads for execution. In this chapter, we will show you how to execute a task dependency graph.<section id="CreateAnExecutor"><h2><a href="#CreateAnExecutor">Create an Executor</a></h2>To execute a taskflow, you need to create an executor of type <a href="classtf_1_1Executor.html" class="m-doc">tf::Executor</a>. An executor is a thread-safe object that manages a set of worker threads and executes tasks through an efficient work-stealing algorithm. Issuing a call to run a taskflow creates a topology, a data structure to keep track of the execution status of a running graph. <a href="classtf_1_1Executor.html" class="m-doc">tf::Executor</a> takes an unsigned integer to construct with <code>N</code> worker threads. The default value is <a href="http://en.cppreference.com/w/cpp/thread/thread/hardware_concurrency.html" class="m-doc-external">std::thread::hardware_concurrency</a>.<pre class="m-code">tf::Executor executor1; // create an executor with the number of workers

// equal to std::thread::hardware_concurrency

tf::Executor executor2(4); // create an executor of 4 worker threads</pre>An executor can be reused to execute multiple taskflows. In most workloads, you may need only one executor to run multiple taskflows where each taskflow represents a part of a parallel decomposition.</section><section id="ExecuteATaskflow"><h2><a href="#ExecuteATaskflow">Execute a Taskflow</a></h2><a href="classtf_1_1Executor.html" class="m-doc">tf::Executor</a> provides a set of <code>run_*</code> methods, <a href="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069" class="m-doc">tf::Executor::run</a>, <a href="classtf_1_1Executor.html#a6d0617eebc9421f1ba1f82ce6dd02c00" class="m-doc">tf::Executor::run_n</a>, and <a href="classtf_1_1Executor.html#a0f52e9dd64b65aba32ca0e13c1ed300a" class="m-doc">tf::Executor::run_until</a> to run a taskflow for one time, multiple times, or until a given predicate evaluates to true. All methods accept an optional callback to invoke after the execution completes, and return a <a href="classtf_1_1Future.html" class="m-doc">tf::Future</a> for users to access the execution status. The code below shows several ways to run a taskflow.<pre class="m-code"> 1: // Declare an executor and a taskflow

2: tf::Executor executor;

3: tf::Taskflow taskflow;

4:

5: // Add three tasks into the taskflow

6: tf::Task A = taskflow.emplace([] () { std::cout << "This is TaskA\n"; });

7: tf::Task B = taskflow.emplace([] () { std::cout << "This is TaskB\n"; });

8: tf::Task C = taskflow.emplace([] () { std::cout << "This is TaskC\n"; });

9:

10: // Build precedence between tasks

11: A.precede(B, C);

12:

13: tf::Future<void> fu = executor.run(taskflow);

14: fu.wait(); // block until the execution completes

15:

16: executor.run(taskflow, [](){ std::cout << "end of 1 run"; }).wait();

17: executor.run_n(taskflow, 4);

18: executor.wait_for_all(); // block until all associated executions finish

19: executor.run_n(taskflow, 4, [](){ std::cout << "end of 4 runs"; }).wait();

20: executor.run_until(taskflow, [cnt=0] () mutable { return ++cnt == 10; });</pre>Debrief:<ul><li>Lines 6-8 create a taskflow of three tasks A, B, and C</li><li>Lines 13-14 run the taskflow once and wait for completion</li><li>Line 16 runs the taskflow once with a callback to invoke when the execution finishes</li><li>Lines 17-18 run the taskflow four times and use <a href="classtf_1_1Executor.html#ab9aa252f70e9a40020a1e5a89d485b85" class="m-doc">tf::Executor::wait_for_all</a> to wait for completion</li><li>Line 19 runs the taskflow four times and invokes a callback at the end of the forth execution</li><li>Line 20 keeps running the taskflow until the predicate returns true</li></ul>Issuing multiple runs on the same taskflow will automatically synchronize to a sequential chain of executions in the order of run calls.<pre class="m-code">executor.run(taskflow); // execution 1

executor.run_n(taskflow, 10); // execution 2

executor.run(taskflow); // execution 3

executor.wait_for_all(); // execution 1 -> execution 2 -> execution 3</pre><aside class="m-note m-warning"><h4>Attention</h4>A running taskflow must remain alive during its execution. It is your responsibility to ensure a taskflow not being destructed when it is running. For example, the code below can result undefined behavior.</aside><pre class="m-code">tf::Executor executor; // create an executor

// create a taskflow whose lifetime is restricted by the scope

{

tf::Taskflow taskflow;

// add tasks to the taskflow

// ...

// run the taskflow

executor.run(f);

} // leaving the scope will destroy taskflow while it is running,

// resulting in undefined behavior</pre>Similarly, you should avoid touching a taskflow while it is running.<pre class="m-code">tf::Taskflow taskflow;

// Add tasks into the taskflow

// ...

// Declare an executor

tf::Executor executor;

tf::Future<void> future = taskflow.run(f); // non-blocking return

// alter the taskflow while running leads to undefined behavior

f.emplace([](){ std::cout << "Add a new task\n"; });</pre>You must always keep a taskflow alive and must not modify it while it is running on an executor.</section><section id="ExecuteATaskflowWithTransferredOwnership"><h2><a href="#ExecuteATaskflowWithTransferredOwnership">Execute a Taskflow with Transferred Ownership</a></h2>You can transfer the ownership of a taskflow to an executor and run it without wrangling with the lifetime issue of that taskflow. Each <code>run_*</code> method discussed in the previous section comes with an overload that takes a moved taskflow object.<pre class="m-code">tf::Taskflow taskflow;

tf::Executor executor;

taskflow.emplace([](){});

// let the executor manage the lifetime of the submitted taskflow

// now taskflow has no tasks

assert(taskflow.num_tasks() == 0);</pre>However, you should avoid moving a running taskflow which can result in undefined behavior.<pre class="m-code">tf::Taskflow taskflow;

tf::Executor executor;

taskflow.emplace([](){});

// executor does not manage the lifetime of taskflow

executor.run(taskflow);

// error! you cannot move a taskflow while it is running

executor.run(std::move(taskflow));</pre>The correct way to submit a taskflow with moved ownership to an executor is to ensure all previous runs have completed. The executor will automatically release the resources of a moved taskflow right after its execution completes.<pre class="m-code">// submit the taskflow and wait until it completes

executor.run(taskflow).wait();

// now it's safe to move the taskflow to the executor and run it

executor.run(std::move(taskflow));</pre>Likewise, you cannot move a taskflow that is running on an executor. You must wait until all the previous fires of runs on that taskflow complete before calling move.<pre class="m-code">// submit the taskflow and wait until it completes

// now it's safe to move the taskflow to another

tf::Taskflow moved_taskflow(std::move(taskflow));</pre></section><section id="ThreadSafety"><h2><a href="#ThreadSafety">Touch an Executor from Multiple Threads</a></h2>All <code>run_*</code> methods are thread-safe. You can have multiple threads call these methods from an executor to run different taskflows. However, the order which taskflow runs first is non-deterministic and is up to the runtime.<pre class="m-code"> 1: tf::Executor executor;

2:

3: for(int i=0; i<10; ++i) {

4: std::thread([i, &](){

5: // ... modify my taskflow at i

6: executor.run(taskflows[i]); // run my taskflow at i

7: }).detach();

8: }

9:

10: executor.wait_for_all();</pre></section><section id="QueryTheWorkerID"><h2><a href="#QueryTheWorkerID">Query the Worker Identieir</a></h2>Each worker in an executor has an unique integer identifier in the range <code>[0, N)</code> that can be queried by the caller thread using <a href="classtf_1_1Executor.html#a6487d589cb1f6b078b69fd3bb1082345" class="m-doc">tf::Executor::this_worker_id</a>. If the caller thread is not a worker in the executor, <code>-1</code> is returned. This method is convenient for users to maintain a one-to-one mapping between a worker and its application data structure.<pre class="m-code">std::vector<int> worker_vectors[8]; // one vector per worker

tf::Taskflow taskflow;

tf::Executor executor(8); // an executor of eight workers

assert(executor.this_worker_id() == -1); // master thread is not a worker

taskflow.emplace([&](){

int id = executor.this_worker_id(); // in the range [0, 8)

auto& vec = worker_vectors[worker_id];

// ...

});</pre></section><section id="ObserveThreadActivities"><h2><a href="#ObserveThreadActivities">Observe Thread Activities</a></h2>You can observe thread activities in an executor when a worker thread participates in executing a task and leaves the execution using <a href="classtf_1_1ObserverInterface.html" class="m-doc">tf::ObserverInterface</a> – an interface class that provides a set of methods for you to define what to do when a thread enters and leaves the execution context of a task.<pre class="m-code">class ObserverInterface {

virtual ~ObserverInterface() = default;

virtual void set_up(size_t num_workers) = 0;

virtual void on_entry(size_t worker_id, tf::TaskView task_view) = 0;

virtual void on_exit(size_t worker_id, tf::TaskView task_view) = 0;

};</pre>There are three methods you must define in your derived class, <a href="classtf_1_1ObserverInterface.html#a41e6e62f12bf9d9dc4fa74632f6825d9" class="m-doc">tf::ObserverInterface::set_up</a>, <a href="classtf_1_1ObserverInterface.html#a3e3a9f7f1d43691794e487b8787b01a0" class="m-doc">tf::ObserverInterface::on_entry</a>, and <a href="classtf_1_1ObserverInterface.html#aa59a59a59eadd4eb6ba20ecdfcae882b" class="m-doc">tf::ObserverInterface::on_exit</a>. The method, <a href="classtf_1_1ObserverInterface.html#a41e6e62f12bf9d9dc4fa74632f6825d9" class="m-doc">tf::ObserverInterface::set_up</a>, is a constructor-like method that will be called by the executor when the observer is constructed. It passes an argument of the number of workers to observer in the executor. You may use it to preallocate or initialize data storage, e.g., an independent vector for each worker. The methods, <a href="classtf_1_1ObserverInterface.html#a3e3a9f7f1d43691794e487b8787b01a0" class="m-doc">tf::ObserverInterface::on_entry</a> and <a href="classtf_1_1ObserverInterface.html#aa59a59a59eadd4eb6ba20ecdfcae882b" class="m-doc">tf::ObserverInterface::on_exit</a>, are called by a worker thread before and after the execution context of a task, respectively. You may use them to record timepoints and calculate the elapsed time of a task.You can associate an executor with one or multiple observers (though one is common) using <a href="classtf_1_1Executor.html#aff77def96ae740d648dd84e571237c83" class="m-doc">tf::Executor::make_observer</a>. We use <a href="http://en.cppreference.com/w/cpp/memory/shared_ptr.html" class="m-doc-external">std::shared_ptr</a> to manage the ownership of an observer. The executor loops through each observer and invoke the corresponding methods accordingly.<pre class="m-code">#include <taskflow/taskflow.hpp>

struct MyObserver : public tf::ObserverInterface {

MyObserver(const std::string& name) {

std::cout << "constructing observer " << name << '\n';

}

void set_up(size_t num_workers) override final {

std::cout << "setting up observer with " << num_workers << " workers\n";

}

void on_entry(size_t w, tf::TaskView tv) override final {

std::ostringstream oss;

oss << "worker " << w << " ready to run " << tv.name() << '\n';

std::cout << oss.str();

}

void on_exit(size_t w, tf::TaskView tv) override final {

std::ostringstream oss;

oss << "worker " << w << " finished running " << tv.name() << '\n';

}

};

int main(){

tf::Executor executor(4);

// Create a taskflow of eight tasks

tf::Taskflow taskflow;

auto A = taskflow.emplace([] () { std::cout << "1\n"; }).name("A");

auto B = taskflow.emplace([] () { std::cout << "2\n"; }).name("B");

auto C = taskflow.emplace([] () { std::cout << "3\n"; }).name("C");

auto D = taskflow.emplace([] () { std::cout << "4\n"; }).name("D");

auto E = taskflow.emplace([] () { std::cout << "5\n"; }).name("E");

auto F = taskflow.emplace([] () { std::cout << "6\n"; }).name("F");

auto G = taskflow.emplace([] () { std::cout << "7\n"; }).name("G");

auto H = taskflow.emplace([] () { std::cout << "8\n"; }).name("H");

// create an observer

std::shared_ptr<MyObserver> observer = executor.make_observer<MyObserver>(

"MyObserver"

);

// run the taskflow

// remove the observer (optional)

executor.remove_observer(std::move(observer));

return 0;

}</pre>The above code produces the following output:<pre class="m-code">constructing observer MyObserver

setting up observer with 4 workers

worker 2 ready to run A

1

worker 2 finished running A

worker 2 ready to run B

2

worker 1 ready to run C

worker 2 finished running B

3

worker 2 ready to run D

worker 3 ready to run E

worker 1 finished running C

4

5

worker 1 ready to run F

worker 2 finished running D

worker 3 finished running E

6

worker 2 ready to run G

worker 3 ready to run H

worker 1 finished running F

7

8

worker 2 finished running G

worker 3 finished running H</pre>It is expected each line of <a href="http://en.cppreference.com/w/cpp/io/basic_ostream.html" class="m-doc-external">std::cout</a> interleaves with each other as there are four workers participating in task scheduling. However, the ready message always appears before the corresponding task message (e.g., numbers) and then the finished message.</section>

</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–2021. 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>

taskflow/docs/ExecuteTaskflow.html at master · yhcpp/taskflow · GitHub

Expand file tree

Breadcrumbs

ExecuteTaskflow.html

Latest commit

History

Breadcrumbs

ExecuteTaskflow.html

File metadata and controls