<para>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.</para><sect1id="ExecuteTaskflow_1CreateAnExecutor">
<title>Create an Executor</title>
<para>To execute a taskflow, you need to create an <emphasis>executor</emphasis> of type <ref refid="classtf_1_1Executor" kindref="compound">tf::Executor</ref>. An executor is a <emphasis>thread-safe</emphasis> object that manages a set of worker threads and executes tasks through an efficient <emphasis>work-stealing</emphasis> algorithm. Issuing a call to run a taskflow creates a <emphasis>topology</emphasis>, a data structure to keep track of the execution status of a running graph. <ref refid="classtf_1_1Executor" kindref="compound">tf::Executor</ref> takes an unsigned integer to construct with <computeroutput>N</computeroutput> worker threads. The default value is <ref refid="cpp/thread/thread/hardware_concurrency" kindref="compound" external="/home/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::thread::hardware_concurrency</ref>.</para><para><programlisting filename=".cpp"><codeline><highlight class="normal"><ref refid="classtf_1_1Executor" kindref="compound">tf::Executor</ref><sp/>executor1;<sp/><sp/><sp/><sp/><sp/></highlight><highlight class="comment">//<sp/>create<sp/>an<sp/>executor<sp/>with<sp/>the<sp/>number<sp/>of<sp/>workers</highlight><highlight class="normal"></highlight></codeline>
</programlisting></para><para>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.</para></sect1>
<sect1id="ExecuteTaskflow_1ExecuteATaskflow">
<title>Execute a Taskflow</title>
<para><ref refid="classtf_1_1Executor" kindref="compound">tf::Executor</ref> provides a set of <computeroutput>run_*</computeroutput> methods, <ref refid="classtf_1_1Executor_1a519777f5783981d534e9e53b99712069" kindref="member">tf::Executor::run</ref>, <ref refid="classtf_1_1Executor_1a6d0617eebc9421f1ba1f82ce6dd02c00" kindref="member">tf::Executor::run_n</ref>, and <ref refid="classtf_1_1Executor_1a0f52e9dd64b65aba32ca0e13c1ed300a" kindref="member">tf::Executor::run_until</ref> 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 <ref refid="classtf_1_1Future" kindref="compound">tf::Future</ref> for users to access the execution status. The code below shows several ways to run a taskflow.</para><para><programlisting filename=".cpp"><codeline><highlight class="normal"><sp/>1:<sp/></highlight><highlight class="comment">//<sp/>Declare<sp/>an<sp/>executor<sp/>and<sp/>a<sp/>taskflow</highlight><highlight class="normal"></highlight></codeline>
<listitem><para>Lines 6-8 create a taskflow of three tasks A, B, and C </para></listitem>
<listitem><para>Lines 13-14 run the taskflow once and wait for completion </para></listitem>
<listitem><para>Line 16 runs the taskflow once with a callback to invoke when the execution finishes </para></listitem>
<listitem><para>Lines 17-18 run the taskflow four times and use <refrefid="classtf_1_1Executor_1ab9aa252f70e9a40020a1e5a89d485b85"kindref="member">tf::Executor::wait_for_all</ref> to wait for completion </para></listitem>
<listitem><para>Line 19 runs the taskflow four times and invokes a callback at the end of the forth execution </para></listitem>
<listitem><para>Line 20 keeps running the taskflow until the predicate returns true</para></listitem>
</itemizedlist>
Issuing multiple runs on the same taskflow will automatically <emphasis>synchronize</emphasis> to a sequential chain of executions in the order of run calls.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal">executor.<refrefid="classtf_1_1Executor_1a519777f5783981d534e9e53b99712069"kindref="member">run</ref>(taskflow);<sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlightclass="comment">//<sp/>execution<sp/>1</highlight><highlightclass="normal"></highlight></codeline>
</programlisting></para><para><simplesectkind="attention"><para>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.</para></simplesect>
</programlisting></para><para>Similarly, you should avoid touching a taskflow while it is running.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal"><refrefid="classtf_1_1Taskflow"kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
<title>Execute a Taskflow with Transferred Ownership</title>
<para>You can transfer the ownership of a taskflow to an executor and run it without wrangling with the lifetime issue of that taskflow. Each <computeroutput>run_*</computeroutput> method discussed in the previous section comes with an overload that takes a <emphasis>moved</emphasis> taskflow object.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal"><refrefid="classtf_1_1Taskflow"kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
</programlisting></para><para>However, you should avoid moving a <emphasis>running</emphasis> taskflow which can result in undefined behavior.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal"><refrefid="classtf_1_1Taskflow"kindref="compound">tf::Taskflow</ref><sp/>taskflow;</highlight></codeline>
</programlisting></para><para>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 <emphasis>after</emphasis> its execution completes.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="comment">//<sp/>submit<sp/>the<sp/>taskflow<sp/>and<sp/>wait<sp/>until<sp/>it<sp/>completes</highlight><highlightclass="normal"></highlight></codeline>
</programlisting></para><para>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.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="comment">//<sp/>submit<sp/>the<sp/>taskflow<sp/>and<sp/>wait<sp/>until<sp/>it<sp/>completes</highlight><highlightclass="normal"></highlight></codeline>
<title>Touch an Executor from Multiple Threads</title>
<para>All <computeroutput>run_*</computeroutput> methods are <emphasis>thread-safe</emphasis>. 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.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal"><sp/>1:<sp/><refrefid="classtf_1_1Executor"kindref="compound">tf::Executor</ref><sp/>executor;</highlight></codeline>
<para>Each worker in an executor has an unique integer identifier in the range <computeroutput>[0, N)</computeroutput> that can be queried by the caller thread using <refrefid="classtf_1_1Executor_1a6487d589cb1f6b078b69fd3bb1082345"kindref="member">tf::Executor::this_worker_id</ref>. If the caller thread is not a worker in the executor, <computeroutput>-1</computeroutput> is returned. This method is convenient for users to maintain a one-to-one mapping between a worker and its application data structure.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="normal"><refrefid="cpp/container/vector"kindref="compound"external="/home/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::vector<int></ref><sp/>worker_vectors[8];<sp/><sp/><sp/><sp/><sp/><sp/><sp/></highlight><highlightclass="comment">//<sp/>one<sp/>vector<sp/>per<sp/>worker</highlight><highlightclass="normal"></highlight></codeline>
<para>You can observe thread activities in an executor when a worker thread participates in executing a task and leaves the execution using <refrefid="classtf_1_1ObserverInterface"kindref="compound">tf::ObserverInterface</ref> <ndash/> an <emphasis>interface</emphasis> 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.</para><para><programlistingfilename=".cpp"><codeline><highlightclass="keyword">class<sp/></highlight><highlightclass="normal">ObserverInterface<sp/>{</highlight></codeline>
</programlisting></para><para>There are three methods you must define in your derived class, <ref refid="classtf_1_1ObserverInterface_1a41e6e62f12bf9d9dc4fa74632f6825d9" kindref="member">tf::ObserverInterface::set_up</ref>, <ref refid="classtf_1_1ObserverInterface_1a3e3a9f7f1d43691794e487b8787b01a0" kindref="member">tf::ObserverInterface::on_entry</ref>, and <ref refid="classtf_1_1ObserverInterface_1aa59a59a59eadd4eb6ba20ecdfcae882b" kindref="member">tf::ObserverInterface::on_exit</ref>. The method, <ref refid="classtf_1_1ObserverInterface_1a41e6e62f12bf9d9dc4fa74632f6825d9" kindref="member">tf::ObserverInterface::set_up</ref>, 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, <ref refid="classtf_1_1ObserverInterface_1a3e3a9f7f1d43691794e487b8787b01a0" kindref="member">tf::ObserverInterface::on_entry</ref> and <ref refid="classtf_1_1ObserverInterface_1aa59a59a59eadd4eb6ba20ecdfcae882b" kindref="member">tf::ObserverInterface::on_exit</ref>, 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.</para><para>You can associate an executor with one or multiple observers (though one is common) using <ref refid="classtf_1_1Executor_1aff77def96ae740d648dd84e571237c83" kindref="member">tf::Executor::make_observer</ref>. We use <ref refid="cpp/memory/shared_ptr" kindref="compound" external="/home/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::shared_ptr</ref> to manage the ownership of an observer. The executor loops through each observer and invoke the corresponding methods accordingly.</para><para><programlisting filename=".cpp"><codeline><highlight class="preprocessor">#include<sp/><<ref refid="taskflow_8hpp" kindref="compound">taskflow/taskflow.hpp</ref>></highlight><highlight class="normal"></highlight></codeline>
</programlisting></para><para>The above code produces the following output:</para><para><programlistingfilename=".bash"><codeline><highlightclass="normal">constructing<sp/>observer<sp/>MyObserver</highlight></codeline>
</programlisting></para><para>It is expected each line of <refrefid="cpp/io/basic_ostream"kindref="compound"external="/home/twhuang/Code/taskflow/doxygen/cppreference-doxygen-web.tag.xml">std::cout</ref> interleaves with each other as there are four workers participating in task scheduling. However, the <emphasis>ready</emphasis> message always appears before the corresponding task message (e.g., numbers) and then the <emphasis>finished</emphasis> message. </para></sect1>