task_scheduler_observer Class extensions

Summary

The task_scheduler_observer Class is extended to control when worker threads sleep and to observe when the threads join or leave a task scheduler arena. Before these extensions, a task_scheduler_observer would only observe when a worker thread would join and exit the global task scheduler.

CAUTION

task_scheduler_observer is not suitable for FPU settings management. Using it for this purpose will cause undefined behavior. See Section Floating-point Settings for more details.

Syntax

class task_scheduler_observer;

Header

#define TBB_PREVIEW_LOCAL_OBSERVER 1
#include "tbb/task_scheduler_observer.h"

Members

namespace tbb {
  class task_scheduler_observer {
  public:
    explicit task_scheduler_observer( bool local = false );
    explicit task_scheduler_observer( task_arena & a );

    // See task_scheduler_observer for the methods
    // not related to local observer ...

#if TBB_USE_PREVIEW_BINARY
    enum { keep_awake = false, allow_sleep = true };
    // Functional with preview binary only
    virtual bool may_sleep() { return allow_sleep; }
#endif
  };
}

Example: setting thread affinity

The following example sketches the code of an observer used to pin worker threads to hardware threads.

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

Example: keeping worker threads active

The following is a code snippet of an observer that prevents worker threads from sleeping while constructed, and allows them to sleep after observer destruction. You can use this observer to denote the scope of continuing parallel computation.

class computation_scope: public tbb::task_scheduler_observer {
public:
  computation_scope( ) { observe(true); } // activate the observer
  /*override*/ bool may_sleep( ) {
    return keep_awake;
  }
};

void usage() {
  non_TBB_code();
  {
    computation_scope protector(); // keeps worker threads active
    for(int i = 0; i < N; i++)
        tbb::parallel_for(0, M, ProcessingFunctor());
  }
  non_TBB_code();
}
The following table provides additional information on the members of this template class.
Member Description
explicit task_scheduler_observer( bool local = false )

Constructs a task_scheduler_observer object in an inactive state (observation is disabled). If local is false, it does not differ from the global semantics described for task_scheduler_observer. If local is true, and the observer has been activated, the entry notifications are invoked only for threads in current arena. Correspondently, a thread receives exit notifications when it leaves this arena.

explicit task_scheduler_observer( task_arena & )

Constructs a task_scheduler_observer object in the inactive state (observation is disabled) tied to the specified task_arena. It receives notifications related only to this specified arena.

Note

Invocation of observe(true) for such an object can force initialization of the internal arena representation of the specified task_arena object
virtual bool may_sleep()

The callback is invoked for a global observer in a worker thread before it goes to sleep. If it returns keep_awake, the thread keeps actively looking for new work during some time instead of going to sleep immediately.

Note

The callback can be invoked periodically by the same thread and concurrently with other threads. It will not be called for local observer mode, for master threads, or if a worker thread must unconditionally return to a resource manager. A thread may call may_sleep() before other callbacks including on_scheduler_entry().

Note

The application must be linked against the Preview library for this method to take effect.

See Also