task_scheduler_init Class

Summary

Class that explicitly represents thread's interest in task scheduling services.

Syntax

class task_scheduler_init;

Header

#include "tbb/task_scheduler_init.h"

Description

Using task_scheduler_init is optional in Intel® Threading Building Blocks (Intel® TBB) 2.2. By default, Intel® TBB 2.2 automatically creates a task scheduler the first time that a thread uses task scheduling services and destroys it when the last such thread exits.

An instance of task_scheduler_init can be used to control the following aspects of the task scheduler:

  • When the task scheduler is constructed and destroyed.

  • The number of threads used by the task scheduler.

  • The stack size for worker threads.

To override the automatic defaults for task scheduling, a task_scheduler_init must become active before the first use of task scheduling services.

A task_scheduler_init is either "active" or "inactive".

The default constructor for a task_scheduler_init activates it, and the destructor deactivates it. To defer activation, pass the value task_scheduler_init::deferred to the constructor. Such a task_scheduler_init may be activated later by calling method initialize. Destruction of an active task_scheduler_init implicitly deactivates it. To deactivate it earlier, call method terminate.

An optional parameter to the constructor and method initialize allows you to specify the number of threads to be used for task execution. This parameter is useful for scaling studies during development, but should not be set for production use.

Tip

The reason for not specifying the number of threads in production code is that in a large software project, there is no way for various components to know how many threads would be optimal for other threads. Hardware threads are a shared global resource. It is best to leave the decision of how many threads to use to the task scheduler.

Note

The task scheduler captures floating-point settings from the current thread at the moment of its initialization. The captured floating-point settings are propagated to all worker threads. See Section Floating-point Settings for more details.

To minimize time overhead, it is best to rely upon automatic creation of the task scheduler, or create a single task_scheduler_init object whose activation spans all uses of the library's task scheduler. A task_scheduler_init is not assignable or copy-constructible.

Example

// Sketch of one way to do a scaling study
#include <iostream>
#include "tbb/task_scheduler_init.h"
 
int main() {
     int n = task_scheduler_init::default_num_threads();
     for( int p=1; p<=n; ++p ) {
         // Construct task scheduler with p threads
         task_scheduler_init init(p);
         tick_count t0 = tick_count::now();
          ... execute parallel algorithm using task or
              template algorithm here...
         tick_count t1 = tick_count::now();
         double t = (t1-t0).seconds();
         cout << "time = " << t << " with " << p << "threads\n";
         // Implicitly destroy task scheduler.
     }
     return 0;
}

Members

  namespace tbb {
        typedef unsigned-integral-type stack_size_type;
     
        class task_scheduler_init {
        public:
            static const int automatic = implementation-defined;
            static const int deferred = implementation-defined;
            task_scheduler_init( int max_threads=automatic, 
                                 stack_size_type thread_stack_size=0 );
            ~task_scheduler_init();
            void initialize( int max_threads=automatic );
            void terminate();
            static int default_num_threads();
            bool is_active() const;
        };
    } // namespace tbb
For more complete information about compiler optimizations, see our Optimization Notice.