taskflow/docs/RequestCancellation.html at task_isolation · ModuleWorks/taskflow · GitHub

History

150 lines (141 loc) · 14.5 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

<!DOCTYPE html>

<head>

<title>Cookbook » Request Cancellation | 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> »

Request Cancellation

</h1>

<h3>Contents</h3>

<ul>

<li><a href="#CancelARunningTaskflow">Cancel Execution of Taskflows</a></li>

<li><a href="#UnderstandTheLimitationsOfCancellation">Understand the Limitations of Cancellation</a></li>

</ul>

</nav>

This chapters discusses how to cancel submitted tasks.<section id="CancelARunningTaskflow"><h2><a href="#CancelARunningTaskflow">Cancel Execution of Taskflows</a></h2>When you submit a taskflow to an executor (e.g., <a href="classtf_1_1Executor.html#a519777f5783981d534e9e53b99712069" class="m-doc">tf::Executor::run</a>), the executor returns a <a href="classtf_1_1Future.html" class="m-doc">tf::Future</a> object that will hold the result of the execution. <a href="classtf_1_1Future.html" class="m-doc">tf::Future</a> is a derived class from <a href="http://en.cppreference.com/w/cpp/thread/future.html" class="m-doc-external">std::future</a>. In addition to base methods of <a href="http://en.cppreference.com/w/cpp/thread/future.html" class="m-doc-external">std::future</a>, you can call <a href="classtf_1_1Future.html#a3bf5f104864ab2590b6409712d3a469b" class="m-doc">tf::Future::cancel</a> to cancel the execution of a running taskflow. The following example cancels a submission of a taskflow that contains 1000 tasks each running one second.<pre class="m-code">tf::Executor executor;

tf::Taskflow taskflow;

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

taskflow.emplace([](){

std::this_thread::sleep_for(std::chrono::seconds(1));

});

}

// submit the taskflow

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

// request to cancel the above submitted execution

fu.cancel();

// wait until the cancellation completes

fu.get();</pre><aside class="m-note m-warning"><h4>Attention</h4><a href="classtf_1_1Future.html#a3bf5f104864ab2590b6409712d3a469b" class="m-doc">tf::Future::cancel</a> is non-deterministic and out-of-order.</aside>When you request a cancellation, the executor will stop scheduling the rest tasks of the taskflow. Tasks that are already running will continue to finish, but their successor tasks will not be scheduled to run. A cancellation is considered complete when all these running tasks finish. To wait for a cancellation to complete, you may explicitly call <code>tf::Future::get</code>.<aside class="m-note m-warning"><h4>Attention</h4>It is your responsibility to ensure that the taskflow remains alive before the cancellation completes.</aside>For instance, the following code results in undefined behavior:<pre class="m-code">tf::Executor executor;

{

tf::Taskflow taskflow;

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

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

}

tf::Future fu = executor.run(taskflow);

fu.cancel(); // there can still be task running after cancellation

} // destroying taskflow here can result in undefined behavior</pre>The undefined behavior problem exists because <a href="classtf_1_1Future.html#a3bf5f104864ab2590b6409712d3a469b" class="m-doc">tf::Future::cancel</a> does not guarantee an immediate cancellation. To fix the problem, call <code>get</code> to ensure the cancellation completes before the end of the scope destroys the taskflow.<pre class="m-code">tf::Executor executor;

{

tf::Taskflow taskflow;

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

}

fu.get(); // waits until the cancellation completes

}</pre></section><section id="UnderstandTheLimitationsOfCancellation"><h2><a href="#UnderstandTheLimitationsOfCancellation">Understand the Limitations of Cancellation</a></h2>Canceling the execution of a running taskflow has the following limitations:<ul><li>Cancellation is non-preemptive. A running task will not be cancelled until it finishes.</li><li>Cancelling a taskflow with tasks acquiring and/or releasing <a href="classtf_1_1Semaphore.html" class="m-doc">tf::Semaphore</a> results is currently not supported.</li></ul>We may overcome these limitations in the future releases.</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–2025. Generated by <a href="https://doxygen.org/">Doxygen</a> 1.12.0 and <a href="https://mcss.mosra.cz/">m.css</a>.

</div>

</nav></footer>

</body>

</html>

taskflow/docs/RequestCancellation.html at task_isolation · ModuleWorks/taskflow · GitHub

Expand file tree

Breadcrumbs

RequestCancellation.html

Latest commit

History

Breadcrumbs

RequestCancellation.html

File metadata and controls