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

History

161 lines (154 loc) · 22.6 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

<!DOCTYPE html>

<head>

<title>Cookbook » Asynchronous Tasking | 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> »

Asynchronous Tasking

</h1>

<h3>Contents</h3>

<ul>

<li><a href="#LaunchAsynchronousTasksFromAnExecutor">Launch Asynchronous Tasks from an Executor</a></li>

<li><a href="#LaunchAsynchronousTasksFromAnSubflow">Launch Asynchronous Tasks from a Subflow</a></li>

</ul>

</nav>

This chapters discusses how to launch tasks asynchronously so that you can incorporate independent, dynamic parallelism in your taskflows.<section id="LaunchAsynchronousTasksFromAnExecutor"><h2><a href="#LaunchAsynchronousTasksFromAnExecutor">Launch Asynchronous Tasks from an Executor</a></h2>Taskflow executor provides a STL-styled method, <a href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" class="m-doc">tf::Executor::async</a>, for you to run a callable object asynchronously. The method returns a <a href="classtf_1_1Future.html" class="m-doc">tf::Future</a> object derived from <a href="https://en.cppreference.com/w/cpp/thread/future">std::future</a> that will eventually hold the result of that function call. The result may be optional due to <a href="classtf_1_1Future.html#a3bf5f104864ab2590b6409712d3a469b" class="m-doc">tf::Future::cancel</a> (see <a href="RequestCancellation.html" class="m-doc">Request Cancellation</a> for details).<pre class="m-code">tf::Future<std::optional<int>> future = executor.async([](){ return 1; });

executor.wait_for_all();

assert(future.get() == 1);

tf::Future<void> future_of_void_return = executor.async([](){});

future_of_void_return.get();</pre><aside class="m-note m-info"><h4>Note</h4>The future object returned from <a href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" class="m-doc">tf::Executor::async</a> does not block on destruction.</aside>If you do not need the return value or the future, you can use <a href="classtf_1_1Executor.html#abf71e7ec0026ddfce79c912264369bc9" class="m-doc">tf::Executor::silent_async</a> which has less overhead of creating an asynchronous task compared to <a href="classtf_1_1Executor.html#a1e6866c8f1b6a2e932f06d0b4eb032c0" class="m-doc">tf::Executor::async</a>.<pre class="m-code">executor.silent_async([](){

// just do some stuff in the background ...

});</pre>Launching asynchronous tasks from an executor is thread-safe and can be called from multiple threads or from the execution of a task. Our scheduler autonomously detects whether an asynchronous task is submitted from an external thread or a worker thread and schedules its execution in an efficient work-stealing loop.<pre class="m-code">tf::Task my_task = taskflow.emplace([&](){

// do some stuff

// ...

// launch an asynchronous task from my_task

executor.async([&](){

// do another asynchronous work

// ...

// launch another asynchronous task

})

});

executor.run(taskflow);

executor.wait_for_all(); // wait for all tasks to finish</pre><aside class="m-note m-info"><h4>Note</h4>Asynchronous tasks created from an executor does not belong to any taskflows.</aside>You can name an asynchronous task to facilitate profiling by using the methods <a href="classtf_1_1Executor.html#a51acee1670e9f246c7ccd7f6a63f1524" class="m-doc">tf::Executor::named_async</a> and <a href="classtf_1_1Executor.html#a1febfaa7a99cac8466263c58fd2a7c06" class="m-doc">tf::Executor::named_silent_async</a>.<pre class="m-code">tf::Future<void> future = executor.named_async("name of the task", [](){});

executor.silent_named_async("another name of the task", [](){});</pre></section><section id="LaunchAsynchronousTasksFromAnSubflow"><h2><a href="#LaunchAsynchronousTasksFromAnSubflow">Launch Asynchronous Tasks from a Subflow</a></h2>You can launch asynchronous tasks from a subflow (<a href="classtf_1_1Subflow.html" class="m-doc">tf::Subflow</a>) using <a href="classtf_1_1Subflow.html#a70681068507b224a96df69cc1f3168f1" class="m-doc">tf::Subflow::async</a>. Asynchronous tasks created from a subflow are, and only, used with join (<a href="classtf_1_1Subflow.html#a59fcac1323e70d920088dd37bd0be245" class="m-doc">tf::Subflow::join</a>) to describe independent tasks that are dynamically spawned during the execution of that subflow. When the subflow joins, all asynchronous tasks are guaranteed to finish. The following code creates 100 asynchronous tasks from a subflow, and these asynchronous tasks will complete by the time the subflow joins.<pre class="m-code">tf::Taskflow taskflow;

tf::Executor executor;

std::atomic<int> counter{0};

taskflow.emplace([&] (tf::Subflow& sf){

std::vector<tf::Future<void>> futures;

for(int i=0; i<100; i++) {

futures.emplace_back(sf.async([&](){ ++counter; }));

}

sf.join(); // all of the 100 asynchronous tasks will finish by this join

assert(counter == 100);

});

tf::Executor executor;

sf.silent_async([&](){ ++counter; });

}

});

executor.run(taskflow).wait();</pre>Creating asynchronous tasks from a subflow allows users to describe, for example, recursive algorithms that define only division without conquering or merging (e.g., parallel quick sort).<aside class="m-note m-warning"><h4>Attention</h4>You should only create asynchronous tasks from a joined subflow. Launching asynchronous tasks from a detached subflow results in undefined behavior.</aside>Similar to <a href="classtf_1_1Executor.html#a51acee1670e9f246c7ccd7f6a63f1524" class="m-doc">tf::Executor::named_async</a> and <a href="classtf_1_1Executor.html#a1febfaa7a99cac8466263c58fd2a7c06" class="m-doc">tf::Executor::named_silent_async</a>, you can name an asynchronous task in <a href="classtf_1_1Subflow.html" class="m-doc">tf::Subflow</a> to facilitate profiling by using the methods <a href="classtf_1_1Subflow.html#ae528c2de98ec89afc50b8815c0306b5e" class="m-doc">tf::Subflow::named_async</a> and <a href="classtf_1_1Subflow.html#a3290b8f729c4511f2023199e4c067951" class="m-doc">tf::Subflow::named_silent_async</a>.<pre class="m-code">taskflow.emplace([](tf::Subflow& sf){

tf::Future<void> future = sf.named_async("name of the task", [](){});

sf.silent_named_async("another name of the task", [](){});

sf.join();

});</pre></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–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

AsyncTasking.html

Latest commit

History

AsyncTasking.html

File metadata and controls