@section C6MonitorThreadActivities Monitor Thread Activities

Knowing the thread activities is very important for performance analysis.

Cpp-Taskflow provides a tf::ExecutorObserver to let users create an observer to record an executor's task execution. The following example shows creating an observer through the executor's tf::Executor::make_observer method.

@code{.cpp}

tf::Taskflow taskflow;

auto observer = taskflow.share_executor()->make_observer<tf::ExecutorObserver>();

@endcode

Note that each executor can only have an observer at a time and creating observer during task execution

will result in undefined behavior. An observer will automatically record the start and end timestamps

of each executed task. Users can query, dump or remove the timestamps through the tf::ExecutorObserver::num_tasks,

tf::ExecutorObserver::dump and tf::ExecutorObserver::clear methods.

@code{.cpp}

1. tf::Taskflow taskflow;

2. auto observer = taskflow.share_executor()->make_observer<tf::ExecutorObserver>();

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

4. taskflow.wait_for_all();

5.

6. // Query the total number of tasks (number of timestamp pairs)

7. auto num_tasks = observer->num_tasks();

8.

9. // Dump the timestamps in JSON format

10. std::string timestamps = observer->dump();

11.

12. // Remove all timestamps

13. observer->clear();

@endcode

Debrief:

@li Line 2-4 creates an observer and a task dependency graph with four tasks and dispatch the tasks to execution.

@li Line 7 query the total number of tasks (number of timestamp pair) through observer

@li Line 10 dump the timestamps to a std::string in JSON format

@li Line 13 remove all timestamps in the observer

Cpp-Taskflow also supports visualization of thread activities. Users can use Chrome (or Chromium on Linux)

browser following below steps to plot the executed tasks as temporal sequences:

@li Step 1: dump the timestamps in observer to a JSON file

@li Step 2: launch the Chrome browser and open a tab with the url: chrome://tracing

@li Step 3: load the JSON file

The resuling plot is like this:

@image html images/timeline.png width=80%

Tasks will be categorized by the executing thread and each task is named with @em i_j where @em i is the thread id and

@em j is the task number. Users can select individual task to know its duration and pan or zoom the timeline to go into

a detailed view.

Users can also customize methods of observer to monitor the behavior of an executor through

inheriting the tf::ExecutorObserverInterface class.

There are three methods users can customize: tf::ExecutorObserverInterface::set_up,

tf::ExecutorObserverInterface::on_entry and tf::ExecutorObserverInterface::on_exit.

The tf::ExecutorObserverInterface::set_up takes the number of threads in an executor as the input argument and

an executor calls this method once to prepare the observer after the observer is constructed.

A thread will call the tf::ExecutorObserverInterface::on_entry and tf::ExecutorObserverInterface::on_exit methods respectively

before and after executing a task, and both methods take the thread id as input argument. Notice that the

tf::ExecutorObserverInterface::on_entry and tf::ExecutorObserverInterface::on_exit can be invoked by multiple

threads concurrently and therefore they must be thread-safe.