# 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

## Feedback

Loading feedback...