tbb::task_scheduler_init Class Reference
Task Scheduling

Class delimiting the scope of task scheduler activity. More...

`#include <task_scheduler_init.h>`

Inheritance diagram for tbb::task_scheduler_init:
Collaboration diagram for tbb::task_scheduler_init:

## Public Member Functions

void __TBB_EXPORTED_METHOD | initialize (int number_of_threads=automatic)
| Ensure that scheduler exists for this thread. More...
void __TBB_EXPORTED_METHOD | initialize (int number_of_threads, stack_size_type thread_stack_size)
| The overloaded method with stack size parameter. More...
void __TBB_EXPORTED_METHOD | terminate ()
| Inverse of method initialize. More...
| task_scheduler_init (int number_of_threads=automatic, stack_size_type thread_stack_size=0)
| Shorthand for default constructor followed by call to initialize(number_of_threads). More...
| ~task_scheduler_init ()
| Destroy scheduler for this thread if thread has no other live task_scheduler_inits. More...
bool | is_active () const
| Returns true if scheduler is active (initialized); false otherwise. More...

## Static Public Member Functions

static int __TBB_EXPORTED_FUNC | default_num_threads ()
| Returns the number of threads TBB scheduler would create if initialized by default. More...

## Static Public Attributes

static const int | automatic = -1
| Typedef for number of threads that is automatic. More...
static const int | deferred = -2
| Argument to initialize() or constructor that causes initialization to be deferred. More...

## Private Types

enum | ExceptionPropagationMode { propagation_mode_exact = 1u , propagation_mode_captured = 2u , propagation_mode_mask = propagation_mode_exact | propagation_mode_captured }

## Private Member Functions

bool | internal_terminate (bool blocking)
Private Member Functions inherited from tbb::internal::no_copy
| no_copy (const no_copy &)=delete
| no_copy ()=default

## Private Attributes

internal::scheduler * | my_scheduler

## Detailed Description

Class delimiting the scope of task scheduler activity.

A thread can construct a task_scheduler_init object and keep it alive while it uses TBB's tasking subsystem (including parallel algorithms).

This class allows to customize properties of the TBB task pool to some extent. For example it can limit concurrency level of parallel work initiated by the given thread. It also can be used to specify stack size of the TBB worker threads, though this setting is not effective if the thread pool has already been created.

If a parallel construct is used without task_scheduler_init object previously created, the scheduler will be initialized automatically with default settings, and will persist until this thread exits. Default concurrency level is defined as described in task_scheduler_init::initialize().

Definition at line 66 of file task_scheduler_init.h.

## Member Enumeration Documentation

## ExceptionPropagationMode

enum tbb::task_scheduler_init::ExceptionPropagationMode

private

Enumerator
propagation_mode_exact |
propagation_mode_captured |
propagation_mode_mask |

Definition at line 67 of file task_scheduler_init.h.

{
propagation_mode_exact = 1u,
propagation_mode_captured = 2u,
propagation_mode_mask = propagation_mode_exact | propagation_mode_captured
};
tbb::task_scheduler_init::propagation_mode_mask
@ propagation_mode_mask
Definition: task_scheduler_init.h:70
tbb::task_scheduler_init::propagation_mode_exact
@ propagation_mode_exact
Definition: task_scheduler_init.h:68
tbb::task_scheduler_init::propagation_mode_captured
@ propagation_mode_captured
Definition: task_scheduler_init.h:69

## Constructor & Destructor Documentation

## task_scheduler_init()

tbb::task_scheduler_init::task_scheduler_init | ( | int | number_of_threads = `automatic`,
|  | stack_size_type | thread_stack_size = `0`
| ) |  |

inline

Shorthand for default constructor followed by call to initialize(number_of_threads).

Definition at line 123 of file task_scheduler_init.h.

: my_scheduler(NULL)
{
// Two lowest order bits of the stack size argument may be taken to communicate
// default exception propagation mode of the client to be used when the
// client manually creates tasks in the master thread and does not use
// explicit task group context object. This is necessary because newer
// TBB binaries with exact propagation enabled by default may be used
// by older clients that expect tbb::captured_exception wrapper.
// All zeros mean old client - no preference.
__TBB_ASSERT( !(thread_stack_size & propagation_mode_mask), "Requested stack size is not aligned" );
#if TBB_USE_EXCEPTIONS
thread_stack_size |= TBB_USE_CAPTURED_EXCEPTION ? propagation_mode_captured : propagation_mode_exact;
#endif /* TBB_USE_EXCEPTIONS */
initialize( number_of_threads, thread_stack_size );
}
TBB_USE_CAPTURED_EXCEPTION
#define TBB_USE_CAPTURED_EXCEPTION
Definition: tbb_config.h:493
__TBB_ASSERT
#define __TBB_ASSERT(predicate, comment)
No-op version of __TBB_ASSERT.
Definition: tbb_stddef.h:165
tbb::task_scheduler_init::initialize
void __TBB_EXPORTED_METHOD initialize(int number_of_threads=automatic)
Ensure that scheduler exists for this thread.
Definition: governor.cpp:477
tbb::task_scheduler_init::my_scheduler
internal::scheduler * my_scheduler
Definition: task_scheduler_init.h:74

References __TBB_ASSERT, and TBB_USE_CAPTURED_EXCEPTION.

## ~task_scheduler_init()

tbb::task_scheduler_init::~task_scheduler_init | ( |  | ) |

inline

Destroy scheduler for this thread if thread has no other live task_scheduler_inits.

Definition at line 140 of file task_scheduler_init.h.

{
if( my_scheduler )
terminate();
internal::poison_pointer( my_scheduler );
}
tbb::internal::poison_pointer
void poison_pointer(T *__TBB_atomic &)
Definition: tbb_stddef.h:305
tbb::task_scheduler_init::terminate
void __TBB_EXPORTED_METHOD terminate()
Inverse of method initialize.
Definition: governor.cpp:528

References tbb::internal::poison_pointer().

Here is the call graph for this function:

## Member Function Documentation

## default_num_threads()

int tbb::task_scheduler_init::default_num_threads | ( |  | ) |

static

Returns the number of threads TBB scheduler would create if initialized by default.

Result returned by this method does not depend on whether the scheduler has already been initialized.

Because TBB 2.0 does not support blocking tasks yet, you may use this method to boost the number of threads in the TBB's internal pool, if your tasks are doing I/O operations. The optimal number of additional threads depends on how much time your tasks spend in the blocked state.

Before TBB 3.0 U4 this method returned the number of logical CPU in the system. Currently on Windows, Linux and FreeBSD it returns the number of logical CPUs available to the current process in accordance with its affinity mask.

NOTE: The return value of this method never changes after its first invocation. This means that changes in the process affinity mask that took place after this method was first invoked will not affect the number of worker threads in the TBB worker threads pool.

Definition at line 545 of file governor.cpp.

{
return governor::default_num_threads();
}
tbb::internal::governor::default_num_threads
static unsigned default_num_threads()
Definition: governor.h:84

References tbb::internal::governor::default_num_threads().

Here is the call graph for this function:

## initialize() [1/2]

void tbb::task_scheduler_init::initialize | ( | int | number_of_threads,
|  | stack_size_type | thread_stack_size
| ) |  |

The overloaded method with stack size parameter.

Overloading is necessary to preserve ABI compatibility

Definition at line 481 of file governor.cpp.

{
#if __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS
uintptr_t new_mode = thread_stack_size & propagation_mode_mask;
#endif
thread_stack_size &= ~(stack_size_type)propagation_mode_mask;
if( number_of_threads!=deferred ) {
__TBB_ASSERT_RELEASE( !my_scheduler, "task_scheduler_init already initialized" );
__TBB_ASSERT_RELEASE( number_of_threads==automatic || number_of_threads > 0,
"number_of_threads for task_scheduler_init must be automatic or positive" );
internal::generic_scheduler *s = governor::init_scheduler( number_of_threads, thread_stack_size, /*auto_init=*/false );
#if __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS
if ( s->master_outermost_level() ) {
uintptr_t &vt = s->default_context()->my_version_and_traits;
uintptr_t prev_mode = vt & task_group_context::exact_exception ? propagation_mode_exact : 0;
vt = new_mode & propagation_mode_exact ? vt | task_group_context::exact_exception
: new_mode & propagation_mode_captured ? vt & ~task_group_context::exact_exception : vt;
// Use least significant bit of the scheduler pointer to store previous mode.
// This is necessary when components compiled with different compilers and/or
// TBB versions initialize the
my_scheduler = static_cast<scheduler*>((generic_scheduler*)((uintptr_t)s | prev_mode));
}
else
#endif /* __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS */
my_scheduler = s;
} else {
__TBB_ASSERT_RELEASE( !thread_stack_size, "deferred initialization ignores stack size setting" );
}
}
__TBB_ASSERT_RELEASE
#define __TBB_ASSERT_RELEASE(predicate, message)
Definition: tbb_stddef.h:134
s
void const char const char int ITT_FORMAT __itt_group_sync s
Definition: ittnotify_static.h:91
tbb::stack_size_type
std::size_t stack_size_type
Definition: task_scheduler_init.h:42
tbb::task_group_context::exact_exception
@ exact_exception
Definition: task.h:383
tbb::task_scheduler_init::automatic
static const int automatic
Typedef for number of threads that is automatic.
Definition: task_scheduler_init.h:83
tbb::task_scheduler_init::deferred
static const int deferred
Argument to initialize() or constructor that causes initialization to be deferred.
Definition: task_scheduler_init.h:86
tbb::internal::governor::init_scheduler
static generic_scheduler * init_scheduler(int num_threads, stack_size_type stack_size, bool auto_init)
Processes scheduler initialization request (possibly nested) in a master thread.
Definition: governor.cpp:172

References __TBB_ASSERT_RELEASE, tbb::task_group_context::exact_exception, tbb::internal::governor::init_scheduler(), and s.

Here is the call graph for this function:

## initialize() [2/2]

void tbb::task_scheduler_init::initialize | ( | int | number_of_threads = `automatic` | ) |

Ensure that scheduler exists for this thread.

A value of -1 lets TBB decide on the number of threads, which is usually maximal hardware concurrency for this process, that is the number of logical CPUs on the machine (possibly limited by the processor affinity mask of this process (Windows) or of this thread (Linux, FreeBSD). It is preferable option for production code because it helps to avoid nasty surprises when several TBB based components run side-by-side or in a nested fashion inside the same process.

The number_of_threads is ignored if any other task_scheduler_inits currently exist. A thread may construct multiple task_scheduler_inits. Doing so does no harm because the underlying scheduler is reference counted.

Left out-of-line for the sake of the backward binary compatibility

Definition at line 477 of file governor.cpp.

{
initialize( number_of_threads, 0 );
}

## internal_terminate()

bool tbb::task_scheduler_init::internal_terminate | ( | bool | blocking | ) |

private

Definition at line 510 of file governor.cpp.

{
#if __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS
uintptr_t prev_mode = (uintptr_t)my_scheduler & propagation_mode_exact;
my_scheduler = (scheduler*)((uintptr_t)my_scheduler & ~(uintptr_t)propagation_mode_exact);
#endif /* __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS */
generic_scheduler* s = static_cast<generic_scheduler*>(my_scheduler);
my_scheduler = NULL;
__TBB_ASSERT_RELEASE( s, "task_scheduler_init::terminate without corresponding task_scheduler_init::initialize()");
#if __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS
if ( s->master_outermost_level() ) {
uintptr_t &vt = s->default_context()->my_version_and_traits;
vt = prev_mode & propagation_mode_exact ? vt | task_group_context::exact_exception
: vt & ~task_group_context::exact_exception;
}
#endif /* __TBB_TASK_GROUP_CONTEXT && TBB_USE_EXCEPTIONS */
return governor::terminate_scheduler(s, blocking);
}
tbb::internal::governor::terminate_scheduler
static bool terminate_scheduler(generic_scheduler *s, bool blocking)
Processes scheduler termination request (possibly nested) in a master thread.
Definition: governor.cpp:205

References __TBB_ASSERT_RELEASE, tbb::task_group_context::exact_exception, s, and tbb::internal::governor::terminate_scheduler().

Here is the call graph for this function:

## is_active()

bool tbb::task_scheduler_init::is_active | ( |  | ) | const

inline

Returns true if scheduler is active (initialized); false otherwise.

Definition at line 166 of file task_scheduler_init.h.

{ return my_scheduler != NULL; }

## terminate()

void tbb::task_scheduler_init::terminate | ( |  | ) |

Inverse of method initialize.

Definition at line 528 of file governor.cpp.

{
internal_terminate(/*blocking_terminate=*/false);
}
tbb::task_scheduler_init::internal_terminate
bool internal_terminate(bool blocking)
Definition: governor.cpp:510

## Member Data Documentation

## automatic

const int tbb::task_scheduler_init::automatic = -1

static

Typedef for number of threads that is automatic.

Definition at line 83 of file task_scheduler_init.h.

Referenced by tbb::internal::governor::init_scheduler(), and tbb::internal::governor::local_scheduler().

## deferred

const int tbb::task_scheduler_init::deferred = -2

static

Argument to initialize() or constructor that causes initialization to be deferred.

Definition at line 86 of file task_scheduler_init.h.

## my_scheduler

internal::scheduler* tbb::task_scheduler_init::my_scheduler

private

NULL if not currently initialized.

Definition at line 74 of file task_scheduler_init.h.

The documentation for this class was generated from the following files:

- task_scheduler_init.h
- governor.cpp

Copyright © 2005-2020 Intel Corporation. All Rights Reserved.

Intel, Pentium, Intel Xeon, Itanium, Intel XScale and VTune are registered trademarks or trademarks of Intel Corporation or its subsidiaries in the United States and other countries.

* Other names and brands may be claimed as the property of others.