merge pull

Author: TSUNG-WEI HUANG

docs/ExceptionHandling.html

@@ -56,6 +56,7 @@ <h3>Contents</h3>
             <li><a href="#CatchAnExceptionFromASubflow">Catch an Exception from a Subflow</a></li>
             <li><a href="#CatchAnExceptionFromAnAsyncTask">Catch an Exception from an Async Task</a></li>
             <li><a href="#CatchAnExceptionFromACorunLoop">Catch an Exception from a Corun Loop</a></li>
+            <li><a href="#TurnOffExceptionHandling">Turn Off Exception Handling</a></li>
           </ul>
         </nav>
 <p>This chapters discusses how to handle exceptions from a submitted taskflow so you can properly catch or propagate exceptions in your workload.</p><section id="CatchAnExceptionFromARunningTaskflow"><h2><a href="#CatchAnExceptionFromARunningTaskflow">Catch an Exception from a Running Taskflow</a></h2><p>When a task throws an exception, the executor will store that exception in the shared state referenced by the <a href="classtf_1_1Future.html" class="m-doc">tf::<wbr />Future</a> handle. You can catch that exception via calling the <code>get</code> method:</p><pre class="m-code"><span class="n">tf</span><span class="o">::</span><span class="n">Executor</span><span class="w"> </span><span class="n">executor</span><span class="p">;</span>
@@ -220,7 +221,7 @@ <h3>Contents</h3>
 <span class="p">}</span>
 <span class="k">catch</span><span class="p">(</span><span class="k">const</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">runtime_error</span><span class="o">&amp;</span><span class="w"> </span><span class="n">re</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
 <span class="w">  </span><span class="n">std</span><span class="o">::</span><span class="n">cout</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">re</span><span class="p">.</span><span class="n">what</span><span class="p">()</span><span class="w"> </span><span class="o">&lt;&lt;</span><span class="w"> </span><span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
-<span class="p">}</span></pre><p>For the above example, if the exception is not caught with <a href="classtf_1_1Runtime.html#a1c772e90614302024cfa52fa86d75cac" class="m-doc">tf::<wbr />Runtime::<wbr />corun</a>, it will be propagated to its parent task, which is the <a href="classtf_1_1Runtime.html" class="m-doc">tf::<wbr />Runtime</a> object <code>rt</code> in this case. Then, the exception will be propagated to <code>taskflow2</code>.</p></section>
+<span class="p">}</span></pre><p>For the above example, if the exception is not caught with <a href="classtf_1_1Runtime.html#a1c772e90614302024cfa52fa86d75cac" class="m-doc">tf::<wbr />Runtime::<wbr />corun</a>, it will be propagated to its parent task, which is the <a href="classtf_1_1Runtime.html" class="m-doc">tf::<wbr />Runtime</a> object <code>rt</code> in this case. Then, the exception will be propagated to <code>taskflow2</code>.</p></section><section id="TurnOffExceptionHandling"><h2><a href="#TurnOffExceptionHandling">Turn Off Exception Handling</a></h2><p>In some applications, exception handling may not be desirable due to performance concerns, coding style preferences, or platform constraints. Taskflow allows you to disable exception handling entirely at compile time. To do this, simply define the macro <code>TF_DISABLE_EXCEPTION_HANDLING</code> when compiling your program:</p><pre class="m-code"><span class="o">~</span><span class="n">$</span><span class="w"> </span><span class="n">g</span><span class="o">++</span><span class="w"> </span><span class="o">-</span><span class="n">DTF_DISABLE_EXCEPTION_HANDLING</span><span class="w"> </span><span class="n">your_taskflow_prog</span><span class="p">.</span><span class="n">cpp</span></pre><p>Disabling exception handling removes all try-catch blocks from the Taskflow runtime, resulting in a leaner binary and potentially faster execution. However, please note that this also means Taskflow will not catch or report runtime exceptions.</p><aside class="m-note m-warning"><h4>Attention</h4><p>Disabling exception handling means that Taskflow will not catch or report runtime exceptions. Any exception thrown during execution will propagate unchecked and may cause your program to behave abnormally. Use this option only if you are confident that your application does not rely on exception safety.</p></aside></section>
       </div>
     </div>
   </div>

docs/contributors.html

@@ -68,7 +68,7 @@ <h3>Contents</h3>
             <li><a href="#release-3-11-0_miscellaneous_items">Miscellaneous Items</a></li>
           </ul>
         </nav>
-<p>Taskflow 3.11.0 is the newest developing line to new features and improvements we continue to support. It is also where this documentation is generated. Many things are considered <em>experimental</em> and may change or break from time to time. While it may be difficult to be keep all things consistent when introducing new features, we continue to try our best to ensure backward compatibility.</p><section id="release-3-11-0_download"><h2><a href="#release-3-11-0_download">Download</a></h2><p>To download the newest version of Taskflow, please clone the master branch from <a href="https://github.com/taskflow/taskflow">Taskflow&#x27;s GitHub</a>.</p></section><section id="release-3-11-0_system_requirements"><h2><a href="#release-3-11-0_system_requirements">System Requirements</a></h2><p>To use Taskflow v3.11.0, you need a compiler that supports C++17:</p><ul><li>GNU C++ Compiler at least v8.4 with -std=c++17</li><li>Clang C++ Compiler at least v6.0 with -std=c++17</li><li>Microsoft Visual Studio at least v19.27 with /std:c++17</li><li>Apple Clang Xcode Version at least v12.0 with -std=c++17</li><li>Nvidia CUDA Toolkit and Compiler (nvcc) at least v11.1 with -std=c++17</li><li>Intel C++ Compiler at least v19.0.1 with -std=c++17</li><li>Intel DPC++ Clang Compiler at least v13.0.0 with -std=c++17</li></ul><p>Taskflow works on Linux, Windows, and Mac OS X.</p><aside class="m-note m-warning"><h4>Attention</h4><p>Although Taskflow supports primarily C++17, you can enable C++20 compilation through <code>-std=c++20</code> to achieve better performance due to new C++20 features.</p></aside></section><section id="release-3-11-0_summary"><h2><a href="#release-3-11-0_summary">Release Summary</a></h2></section><section id="release-3-11-0_new_features"><h2><a href="#release-3-11-0_new_features">New Features</a></h2><section id="release-3-11-0_taskflow_core"><h3><a href="#release-3-11-0_taskflow_core">Taskflow Core</a></h3><ul><li>added five benchmarks to showcase the capability of <a href="classtf_1_1Runtime.html" class="m-doc">tf::<wbr />Runtime</a><ul><li>fibonacci</li><li>skynet</li><li>integrate</li><li>nqueens</li><li>primes</li></ul></li></ul></section><section id="release-3-11-0_utilities"><h3><a href="#release-3-11-0_utilities">Utilities</a></h3></section></section><section id="release-3-11-0_bug_fixes"><h2><a href="#release-3-11-0_bug_fixes">Bug Fixes</a></h2></section><section id="release-3-11-0_breaking_changes"><h2><a href="#release-3-11-0_breaking_changes">Breaking Changes</a></h2></section><section id="release-3-11-0_documentation"><h2><a href="#release-3-11-0_documentation">Documentation</a></h2></section><section id="release-3-11-0_miscellaneous_items"><h2><a href="#release-3-11-0_miscellaneous_items">Miscellaneous Items</a></h2><p>If you are interested in collaborating with us on applying Taskflow to your projects, please feel free to reach out to <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>!</p></section>
+<p>Taskflow 3.11.0 is the newest developing line to new features and improvements we continue to support. It is also where this documentation is generated. Many things are considered <em>experimental</em> and may change or break from time to time. While it may be difficult to be keep all things consistent when introducing new features, we continue to try our best to ensure backward compatibility.</p><section id="release-3-11-0_download"><h2><a href="#release-3-11-0_download">Download</a></h2><p>To download the newest version of Taskflow, please clone the master branch from <a href="https://github.com/taskflow/taskflow">Taskflow&#x27;s GitHub</a>.</p></section><section id="release-3-11-0_system_requirements"><h2><a href="#release-3-11-0_system_requirements">System Requirements</a></h2><p>To use Taskflow v3.11.0, you need a compiler that supports C++17:</p><ul><li>GNU C++ Compiler at least v8.4 with -std=c++17</li><li>Clang C++ Compiler at least v6.0 with -std=c++17</li><li>Microsoft Visual Studio at least v19.27 with /std:c++17</li><li>Apple Clang Xcode Version at least v12.0 with -std=c++17</li><li>Nvidia CUDA Toolkit and Compiler (nvcc) at least v11.1 with -std=c++17</li><li>Intel C++ Compiler at least v19.0.1 with -std=c++17</li><li>Intel DPC++ Clang Compiler at least v13.0.0 with -std=c++17</li></ul><p>Taskflow works on Linux, Windows, and Mac OS X.</p><aside class="m-note m-warning"><h4>Attention</h4><p>Although Taskflow supports primarily C++17, you can enable C++20 compilation through <code>-std=c++20</code> to achieve better performance due to new C++20 features.</p></aside></section><section id="release-3-11-0_summary"><h2><a href="#release-3-11-0_summary">Release Summary</a></h2></section><section id="release-3-11-0_new_features"><h2><a href="#release-3-11-0_new_features">New Features</a></h2><section id="release-3-11-0_taskflow_core"><h3><a href="#release-3-11-0_taskflow_core">Taskflow Core</a></h3><ul><li>added five benchmarks to showcase the capability of <a href="classtf_1_1Runtime.html" class="m-doc">tf::<wbr />Runtime</a><ul><li>fibonacci</li><li>skynet</li><li>integrate</li><li>nqueens</li><li>primes</li></ul></li></ul></section><section id="release-3-11-0_utilities"><h3><a href="#release-3-11-0_utilities">Utilities</a></h3></section></section><section id="release-3-11-0_bug_fixes"><h2><a href="#release-3-11-0_bug_fixes">Bug Fixes</a></h2></section><section id="release-3-11-0_breaking_changes"><h2><a href="#release-3-11-0_breaking_changes">Breaking Changes</a></h2></section><section id="release-3-11-0_documentation"><h2><a href="#release-3-11-0_documentation">Documentation</a></h2><ul><li>revised <a href="ExceptionHandling.html" class="m-doc">Exception Handling</a></li></ul></section><section id="release-3-11-0_miscellaneous_items"><h2><a href="#release-3-11-0_miscellaneous_items">Miscellaneous Items</a></h2><p>If you are interested in collaborating with us on applying Taskflow to your projects, please feel free to reach out to <a href="https://tsung-wei-huang.github.io/">Dr. Tsung-Wei Huang</a>!</p></section>
       </div>
     </div>
   </div>

docs/release-3-11-0.html

@@ -19,6 +19,10 @@
       <tocsect>
         <name>Catch an Exception from a Corun Loop</name>
         <reference>ExceptionHandling_1CatchAnExceptionFromACorunLoop</reference>
+    </tocsect>
+      <tocsect>
+        <name>Turn Off Exception Handling</name>
+        <reference>ExceptionHandling_1TurnOffExceptionHandling</reference>
     </tocsect>
     </tableofcontents>
     <briefdescription>
@@ -240,7 +244,17 @@ An exception will automatically cancel the execution of its parent taskflow. All
 <codeline><highlight class="normal"><sp/><sp/><ref refid="cpp/io/basic_ostream" kindref="compound" external="/home/thuang295/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref><sp/>&lt;&lt;<sp/>re.what()<sp/>&lt;&lt;<sp/><ref refid="cpp/io/manip/endl" kindref="compound" external="/home/thuang295/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::endl</ref>;</highlight></codeline>
 <codeline><highlight class="normal">}</highlight></codeline>
 </programlisting></para>
-<para>For the above example, if the exception is not caught with <ref refid="classtf_1_1Runtime_1a1c772e90614302024cfa52fa86d75cac" kindref="member">tf::Runtime::corun</ref>, it will be propagated to its parent task, which is the <ref refid="classtf_1_1Runtime" kindref="compound">tf::Runtime</ref> object <computeroutput>rt</computeroutput> in this case. Then, the exception will be propagated to <computeroutput>taskflow2</computeroutput>. </para>
+<para>For the above example, if the exception is not caught with <ref refid="classtf_1_1Runtime_1a1c772e90614302024cfa52fa86d75cac" kindref="member">tf::Runtime::corun</ref>, it will be propagated to its parent task, which is the <ref refid="classtf_1_1Runtime" kindref="compound">tf::Runtime</ref> object <computeroutput>rt</computeroutput> in this case. Then, the exception will be propagated to <computeroutput>taskflow2</computeroutput>.</para>
+</sect1>
+<sect1 id="ExceptionHandling_1TurnOffExceptionHandling">
+<title>Turn Off Exception Handling</title>
+<para>In some applications, exception handling may not be desirable due to performance concerns, coding style preferences, or platform constraints. Taskflow allows you to disable exception handling entirely at compile time. To do this, simply define the macro <computeroutput>TF_DISABLE_EXCEPTION_HANDLING</computeroutput> when compiling your program:</para>
+<para><programlisting filename=".cpp"><codeline><highlight class="normal">~$<sp/>g++<sp/>-DTF_DISABLE_EXCEPTION_HANDLING<sp/>your_taskflow_prog.cpp</highlight></codeline>
+</programlisting></para>
+<para>Disabling exception handling removes all try-catch blocks from the Taskflow runtime, resulting in a leaner binary and potentially faster execution. However, please note that this also means Taskflow will not catch or report runtime exceptions.</para>
+<para><simplesect kind="attention"><para>Disabling exception handling means that Taskflow will not catch or report runtime exceptions. Any exception thrown during execution will propagate unchecked and may cause your program to behave abnormally. Use this option only if you are confident that your application does not rely on exception safety. </para>
+</simplesect>
+</para>
 </sect1>
     </detaileddescription>
     <location file="doxygen/cookbook/exception.dox"/>

docs/xml/ExceptionHandling.xml

@@ -71,6 +71,8 @@
 </listitem>
 <listitem><para><ulink url="https://github.com/xq114">Hoildkv</ulink>: fixed documentation errors in explaining the observer interface of executor </para>
 </listitem>
+<listitem><para><ulink url="https://github.com/IkeOTL">Isaac Yousuf</ulink>: fixed the bug in exception handling for worker loop </para>
+</listitem>
 <listitem><para><ulink url="https://ossia.io/">Jean Michael</ulink>: integrated Taskflow to the OSSIA project and reported feedback in comparison to TBB </para>
 </listitem>
 <listitem><para><ulink url="https://jw-liu.xyz/">Jiawei Liu</ulink>: fixed typos in the documentation </para>

docs/xml/contributors.xml

@@ -110,6 +110,10 @@ Taskflow works on Linux, Windows, and Mac OS X.</para>
 </sect1>
 <sect1 id="release-3-11-0_1release-3-11-0_documentation">
 <title>Documentation</title>
+<para><itemizedlist>
+<listitem><para>revised <ref refid="ExceptionHandling" kindref="compound">Exception Handling</ref></para>
+</listitem></itemizedlist>
+</para>
 </sect1>
 <sect1 id="release-3-11-0_1release-3-11-0_miscellaneous_items">
 <title>Miscellaneous Items</title>

docs/xml/release-3-11-0.xml

@@ -32,6 +32,7 @@ We are grateful for the following contributors (alphabetic order) to the %Taskfl
   @li <a href="https://github.com/guannan-git">Guannan Guo</a>: benchmarked different scheduling algorithms and architectures
   @li <a href="https://github.com/hjxy2012">Hjxy2012</a>: fixed the compilation error in nvcc due to removed features in C++17
   @li <a href="https://github.com/xq114">Hoildkv</a>: fixed documentation errors in explaining the observer interface of executor
+  @li <a href="https://github.com/IkeOTL">Isaac Yousuf</a>: fixed the bug in exception handling for worker loop
   @li <a href="https://ossia.io/">Jean Michael</a>: integrated %Taskflow to the OSSIA project and reported feedback in comparison to TBB
   @li <a href="https://jw-liu.xyz/">Jiawei Liu</a>: fixed typos in the documentation
   @li <a href="https://github.com/juliangilbey">Junlian Gilbey</a>: added the explicit link to libatomic on some archs 

doxygen/contributing/contributors.dox

@@ -296,6 +296,23 @@ For the above example, if the exception is not caught with tf::Runtime::corun,
 it will be propagated to its parent task, which is the tf::Runtime object `rt` in this case.
 Then, the exception will be propagated to `taskflow2`.
 
+@section TurnOffExceptionHandling Turn Off Exception Handling
+
+In some applications, exception handling may not be desirable due to performance concerns, coding style preferences, or platform constraints. %Taskflow allows you to disable exception handling entirely at compile time. 
+To do this, simply define the macro `TF_DISABLE_EXCEPTION_HANDLING` when compiling your program:
+
+@code{.cpp}
+~$ g++ -DTF_DISABLE_EXCEPTION_HANDLING your_taskflow_prog.cpp
+@endcode
+
+Disabling exception handling removes all try-catch blocks from the %Taskflow runtime, resulting in a leaner binary and potentially faster execution. 
+However, please note that this also means %Taskflow will not catch or report runtime exceptions. 
+
+@attention
+Disabling exception handling means that %Taskflow will not catch or report runtime exceptions.
+Any exception thrown during execution will propagate unchecked and may cause your program to behave abnormally.
+Use this option only if you are confident that your application does not rely on exception safety.
+
 */
 
 }

doxygen/cookbook/exception.dox

@@ -55,6 +55,8 @@ through `-std=c++20` to achieve better performance due to new C++20 features.
 
 @section release-3-11-0_documentation Documentation
 
++ revised @ref ExceptionHandling
+
 @section release-3-11-0_miscellaneous_items Miscellaneous Items
 
 If you are interested in collaborating with us on applying %Taskflow to your projects, please feel free to reach out to @twhuang!

doxygen/releases/release-3.11.0.dox

@@ -71,3 +71,18 @@ void throw_re(const char* fname, const size_t line, ArgsT&&... args) {
 
 #define TF_THROW(...) tf::throw_re(__FILE__, __LINE__, __VA_ARGS__);
 
+// ----------------------------------------------------------------------------
+
+#ifdef TF_DISABLE_EXCEPTION_HANDLING
+  #define TF_EXECUTOR_EXCEPTION_HANDLER(worker, node, code_block) \
+    code_block;
+#else
+  #define TF_EXECUTOR_EXCEPTION_HANDLER(worker, node, code_block)  \
+    try {                                          \
+      code_block;                                  \
+    } catch(...) {                                 \
+      _process_exception(worker, node);            \
+    }
+#endif
+
+

taskflow/core/error.hpp

@@ -41,19 +41,7 @@
   #define TF_UNLIKELY(x) (x)
 #endif
 
-// ----------------------------------------------------------------------------
 
-#ifdef TF_DISABLE_EXCEPTION_HANDLING
-  #define TF_EXECUTOR_EXCEPTION_HANDLER(worker, node, code_block) \
-    code_block;
-#else
-  #define TF_EXECUTOR_EXCEPTION_HANDLER(worker, node, code_block)  \
-    try {                                          \
-      code_block;                                  \
-    } catch(...) {                                 \
-      _process_exception(worker, node);            \
-    }
-#endif
 
 // ----------------------------------------------------------------------------