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.