# combinable Class

**Visual Studio 2015**

For the latest documentation on Visual Studio 2017, see Visual Studio 2017 Documentation.

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.

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.

### Public Constructors

Name | Description |
---|---|

combinable::combinable Constructor | Overloaded. Constructs a new `combinable` object. |

combinable::~combinable Destructor | Destroys a `combinable` object. |

### Public Methods

Name | Description |
---|---|

combinable::clear Method | Clears any intermediate computational results from a previous usage. |

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

combinable::combine_each Method | 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. |

combinable::local Method | Overloaded. Returns a reference to the thread-private sub-computation. |

### Public Operators

Name | Description |
---|---|

combinable::operator= Operator | Assigns to a `combinable` object from another `combinable` object. |

For more information, see Parallel Containers and Objects.

`combinable`

**Header:** ppl.h

**Namespace:** concurrency

Clears any intermediate computational results from a previous usage.

void clear();

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.

Destroys a `combinable`

object.

~combinable();

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.

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.

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.

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.