task_scheduler_observer#

[scheduler.task_scheduler_observer]

Class that represents thread interest in task scheduling services.

// Defined in header <oneapi/tbb/task_scheduler_observer.h>

namespace oneapi {
namespace tbb {

   class task_scheduler_observer {
   public:
       task_scheduler_observer();
       explicit task_scheduler_observer( task_arena& a );
       virtual ~task_scheduler_observer();

       void observe( bool state=true );
       bool is_observing() const;

       virtual void on_scheduler_entry( bool is_worker ) {}
       virtual void on_scheduler_exit( bool is_worker } {}
   };

} // namespace tbb
} // namespace oneapi

A task_scheduler_observer permits clients to observe when a thread starts and stops processing tasks, either globally or in a certain task scheduler arena. You typically derive your own observer class from task_scheduler_observer, and override virtual methods on_scheduler_entry or on_scheduler_exit. Observation can be enabled and disabled for an observer instance; it is disabled on creation. Remember to call observe() to enable observation.

Exceptions thrown and not caught in the overridden methods of task_scheduler_observer result in undefined behavior.

Member functions#

task_scheduler_observer()#

Constructs a task_scheduler_observer object in the inactive state (observation is disabled). For a created observer, entry/exit notifications are invoked whenever a worker thread joins/leaves the arena of the observer’s owner thread. If a thread is already in the arena when the observer is activated, the entry notification is called before it executes the first stolen task.

explicit task_scheduler_observer(task_arena&)#

Constructs a task_scheduler_observer object for a given arena in inactive state (observation is disabled). For created observer, entry/exit notifications are invoked whenever a thread joins/leaves arena. If a thread is already in the arena when the observer is activated, the entry notification is called before it executes the first stolen task.

Constructs a task_scheduler_observer object in the inactive state (observation is disabled), which receives notifications from threads entering and exiting the specified task_arena.

~task_scheduler_observer()#

Disables observing and destroys the observer instance. Waits for extant invocations of on_scheduler_entry and on_scheduler_exit to complete.

void observe(bool state = true)#

Enables observing if state is true; disables observing if state is false.

bool is_observing() const#

Returns: True if observing is enabled; false, otherwise.

virtual void on_scheduler_entry(bool is_worker)#

The task scheduler invokes this method for each thread that starts participating in oneTBB work or enters an arena after the observation is enabled. For threads that already execute tasks, the method is invoked before executing the first task stolen after enabling the observation.

If a thread enables the observation and then spawns a task, it is guaranteed that the task, as well as all the tasks it creates, will be executed by threads which have invoked on_scheduler_entry.

The flag is_worker is true if the thread was created by oneTBB; false, otherwise.

Effects: The default behavior does nothing.

virtual void on_scheduler_exit(bool is_worker)#

The task scheduler invokes this method when a thread stops participating in task processing or leaves an arena.

Caution

A process does not wait for the worker threads to clean up, and can terminate before on_scheduler_exit is invoked.

Effects: The default behavior does nothing.

Example#

The following example sketches the code of an observer that pins oneTBB worker threads to hardware threads.

class pinning_observer : public oneapi::tbb::task_scheduler_observer {
public:
    affinity_mask_t m_mask; // HW affinity mask to be used for threads in an arena
    pinning_observer( oneapi::tbb::task_arena &a, affinity_mask_t mask )
        : oneapi::tbb::task_scheduler_observer(a), m_mask(mask) {
        observe(true); // activate the observer
    }
    void on_scheduler_entry( bool worker ) override {
        set_thread_affinity(oneapi::tbb::this_task_arena::current_thread_index(), m_mask);
    }
    void on_scheduler_exit( bool worker ) override {
        restore_thread_affinity();
    }
};