task_arena Class

Summary

Explicit, user-managed task scheduler arena representation.

Syntax

class task_arena;

Header

#define TBB_PREVIEW_TASK_ARENA 1
#include “tbb/task_arena.h”

Description

A task_arena class represents an internal task scheduler object where a number of threads, limited by a maximal concurrency level, share and execute tasks.

The concurrency level of a task_arena is isolated and not affected by previous task_scheduler_init specifications.

A task_arena object keeps a reference to its internal representation, but does not fully control its lifetime. It cannot be destroyed until it contains tasks and/or other worker threads reference it.

Each user thread that explicitly or implicitly creates a task_scheduler_init object contains an implicit internal task arena object. The tasks spawned or enqueued in an arena cannot be executed in a different arena.

This preview feature requires linkage with the Community Preview library.

Members

namespace tbb {
class task_arena {
public:
    static const int automatic = implementation-defined;
    static int current_slot();
    task_arena(int max_concurrency = automatic);
    task_arena(const task_arena &s);
    ~task_arena();
    void initialize(int max_concurrency);
    template<typename F> void enqueue( const F& f );
#if __TBB_TASK_PRIORITY // TODO: remove???
    template<typename F> void enqueue( const F& f, priority_t p );
#endif
    template<typename F> void execute(F& f);
    template<typename F> void execute(const F& f); // TODO:remove?
    void wait_until_empty();
};
}

Examples

The following example runs two paralel_for loops concurrently; one that is scalable and one that is not. The non-scalable loop is limited to at most 2 threads so that the majority of the threads can be saved for the more scalable loop.

tbb::task_scheduler_init def_init; // Use the default number of threads
tbb::task_arena limited(2);// no more than 2 threads in this arena

limited.enqueue([]{ // use at most 2 threads
    tbb::parallel_for(1, N, unscalable_work());
}); 

// Run another job concurrently with the loop above
// It can use the default number of threads:
tbb::parallel_for(1, M, scalable_work());

limited.wait_until_empty(); // ensure async work is finished

The last line of the above example calls wait_until_empty() to wait for all work in the arena to be completed. If you need to wait for a specific subset of tasks to complete, a task_group can be used as shown below:

tbb::task_arena arena;
tbb::task_group tg;

// Enqueue some job(s) in a task group 
for( int i=0; i<N; ++i)
    arena.enqueue([&,=i] { tg.run( F(i) ) });

// Do some other work ...

// Put the wait for the task group inside execute()
// This will wait only for the tasks that are in
// this arena.
arena.execute([&]{ tg.wait(); });