| Home | Libraries | People | FAQ | More

## Function all_reduce

boost::mpi::all_reduce — Combine the values stored by each process into a single value available to all processes.

## Synopsis

    // In header: <boost/mpi/collectives.hpp>

    template<typename T, typename Op>
      void all_reduce(const communicator & comm, const T * value, int n,
                      T * out_value, Op op);
    template<typename T, typename Op>
      void all_reduce(const communicator & comm, const T & value, T & out_value,
                      Op op);
    template<typename T, typename Op>
      T all_reduce(const communicator & comm, const T & value, Op op);
    template<typename T, typename Op>
      void all_reduce(const communicator & comm, inplace_t< T * > value, int n,
                      Op op);
    template<typename T, typename Op>
      void all_reduce(const communicator & comm, inplace_t< T > value, Op op);

## Description

`all_reduce` is a collective algorithm that combines the values stored by each process into a single value available to all processes. The values are combined in a user-defined way, specified via a function object. The type `T` of the values may be any type that is serializable or has an associated MPI data type. One can think of this operation as a `all_gather`, followed by an `std::accumulate()` over the gather values and using the operation `op`.

When the type `T` has an associated MPI data type, this routine invokes `MPI_Allreduce` to perform the reduction. If possible, built-in MPI operations will be used; otherwise, `all_reduce()` will create a custom MPI_Op for the call to MPI_Allreduce.

If wrapped in a ``inplace_t`` object, combine the usage of both input and $c out_value and the local value will be overwritten (a convenience function `inplace` is provided for the wrapping).

Parameters: |
`comm` | The communicator over which the reduction will occur.
`n` | Indicated the size of the buffers of array type.
`op` | The binary operation that combines two values of type `T` and returns a third value of type `T`. For types `T` that has ssociated MPI data types, `op` will either be translated into an `MPI_Op` (via `MPI_Op_create`) or, if possible, mapped directly to a built-in MPI operation. See ``is_mpi_op`` in the `operations.hpp` header for more details on this mapping. For any non-built-in operation, commutativity will be determined by the `is_commmutative` trait (also in `operations.hpp`): users are encouraged to mark commutative operations as such, because it gives the implementation additional lattitude to optimize the reduction operation.
`out_value` | Will receive the result of the reduction operation. If this parameter is omitted, the outgoing value will instead be returned.
`value` | The local value to be combined with the local values of every other process. For reducing arrays, `in_values` is a pointer to the local values to be reduced and `n` is the number of values to reduce. See `reduce` for more information.
Returns: | If no `out_value` parameter is supplied, returns the result of the reduction operation.