combinable Template Class

Summary

Template class for holding thread-local values during a parallel computation that will be merged into a final value.

Syntax

template<typename T> class combinable;

Header

#include "tbb/combinable.h"

Description

A combinable<T> provides each thread with its own local instance of type T.

Members

namespace tbb {
        template <typename T>
        class combinable {
        public:
            combinable();

            template <typename FInit>
            explicit combinable(FInit finit);

            combinable(const combinable& other);
            // Supported since C++11
            combinable(combinable&& other);

            ~combinable();

            combinable& operator=( const combinable& other);
            // Supported since C++11
            combinable& operator=( combinable&& other);

            void clear();

            T& local();
            T& local(bool & exists);

            template<typename FCombine> T combine(FCombine fcombine);
            template<typename Func> void combine_each(Func f);
        };
}
The following table provides additional information on the members of this template class.
Member Description
combinable()

Constructs combinable such that any thread-local instances of T will be created using default construction.

template<typename FInit> explicit combinable(FInit finit)

Constructs combinable such that any thread-local element will be created by copying the result of finit().

CAUTION

The expression finit() must be safe to evaluate concurrently by multiple threads. It is evaluated each time a thread-local element is created.

combinable( const combinable& other );

Constructs a copy of other, so that it has copies of each element in other with the same thread mapping.

combinable( combinable&& other );

Supported since C++11. Constructs combinable by moving the content of other intact. other is left in an unspecified state but can be safely destroyed.

~combinable()

Destroys all thread-local elements in *this.

combinable& operator=( const combinable& other )

Sets *this to be a copy of other.

combinable& operator=( combinable&& other )

Supported since C++11. Moves the content of other to *this intact. other is left in an unspecified state but can be safely destroyed.

void clear()

Removes all elements from *this.

T& local()

If thread-local element does not exist, creates it.

Returns: Reference to thread-local element.

T& local( bool& exists )

Similar to local(), except that exists is set to true if an element was already present for the current thread; false otherwise.

Returns: Reference to thread-local element.

template<typename FCombine>T combine(FCombine fcombine)

Requires: Parameter fcombine should be an associative binary functor with the signature T(T,T) or T(const T&,const T&).

Effects: Computes a reduction over all elements using binary functor fcombine. If there are no elements, creates the result using the same rules as for creating a thread-local element.

Returns: Result of the reduction.

template<typename Func> void combine_each(Func f)

Requires: Parameter f should be a unary functor with the signature void(T) or void(const T&).

Effects: Evaluates f(x) for each instance x of T in *this.

For more complete information about compiler optimizations, see our Optimization Notice.