combinable Class

The combinable<T> object is intended to provide thread-private copies of data, to perform lock-free thread-local sub-computations during parallel algorithms. At the end of the parallel operation, the thread-private sub-computations can then be merged into a final result. This class can be used instead of a shared variable, and can result in a performance improvement if there would otherwise be a lot of contention on that shared variable.

Syntax

template<typename T>
class combinable;

Parameters

T
The data type of the final merged result. The type must have a copy constructor and a default constructor.

Members

Public Constructors

Name	Description
combinable	Overloaded. Constructs a new combinable object.
~combinable Destructor	Destroys a combinable object.

Public Methods

Name	Description
clear	Clears any intermediate computational results from a previous usage.
combine	Computes a final value from the set of thread-local sub-computations by calling the supplied combine functor.
combine_each	Computes a final value from the set of thread-local sub-computations by calling the supplied combine functor once per thread-local sub-computation. The final result is accumulated by the function object.
local	Overloaded. Returns a reference to the thread-private sub-computation.

Public Operators

Name	Description
operator=	Assigns to a combinable object from another combinable object.

Remarks

For more information, see Parallel Containers and Objects.

Inheritance Hierarchy

combinable

Requirements

Header: ppl.h

Namespace: concurrency

clear

Clears any intermediate computational results from a previous usage.

void clear();

combinable

Constructs a new combinable object.

combinable();

template <typename _Function>
explicit combinable(_Function _FnInitialize);

combinable(const combinable& _Copy);

Parameters

_Function
The type of the initialization functor object.

_FnInitialize
A function which will be called to initialize each new thread-private value of the type T. It must support a function call operator with the signature T ().

_Copy
An existing combinable object to be copied into this one.

Remarks

The first constructor initializes new elements with the default constructor for the type T.

The second constructor initializes new elements using the initialization functor supplied as the _FnInitialize parameter.

The third constructor is the copy constructor.

~combinable

Destroys a combinable object.

~combinable();

combine

Computes a final value from the set of thread-local sub-computations by calling the supplied combine functor.

template<typename _Function>
T combine(_Function _FnCombine) const;

Parameters

_Function
The type of the function object that will be invoked to combine two thread-local sub-computations.

_FnCombine
The functor that is used to combine the sub-computations. Its signature is T (T, T) or T (const T&, const T&), and it must be associative and commutative.

Return Value

The final result of combining all the thread-private sub-computations.

combine_each

Computes a final value from the set of thread-local sub-computations by calling the supplied combine functor once per thread-local sub-computation. The final result is accumulated by the function object.

template<typename _Function>
void combine_each(_Function _FnCombine) const;

Parameters

_Function
The type of the function object that will be invoked to combine a single thread-local sub-computation.

_FnCombine
The functor that is used to combine one sub-computation. Its signature is void (T) or void (const T&), and must be associative and commutative.

local

Returns a reference to the thread-private sub-computation.

T& local();

T& local(bool& _Exists);

Parameters

_Exists
A reference to a boolean. The boolean value referenced by this argument will be set to true if the sub-computation already existed on this thread, and set to false if this was the first sub-computation on this thread.

Return Value

A reference to the thread-private sub-computation.

operator=

Assigns to a combinable object from another combinable object.

combinable& operator= (const combinable& _Copy);

Parameters

_Copy
An existing combinable object to be copied into this one.

Return Value

A reference to this combinable object.

See also

concurrency Namespace