| Home | Libraries | People | FAQ | More

## Function scan

boost::mpi::scan — Compute a prefix reduction of values from all processes in the communicator.

## Synopsis

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

    template<typename T, typename Op>
      void scan(const communicator & comm, const T & in_value, T & out_value,
                Op op);
    template<typename T, typename Op>
      T scan(const communicator & comm, const T & in_value, Op op);
    template<typename T, typename Op>
      void scan(const communicator & comm, const T * in_values, int n,
                T * out_values, Op op);

## Description

`scan` is a collective algorithm that combines the values stored by each process with the values of all processes with a smaller rank. The values can be arbitrarily combined, specified via a function object `op`. 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 `gather` to some process, followed by an `std::prefix_sum()` over the gathered values using the operation `op`. The ith process returns the ith value emitted by `std::prefix_sum()`.

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

Parameters:

`comm` | The communicator over which the prefix reduction will occur.
`in_value` | The local value to be combined with the local values of other processes. For the array variant, the `in_values` parameter points to the `n` local values that will be combined.

`op`

The binary operation that combines two values of type `T` into 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`).

`out_value`

If provided, the ith process will receive the value `op`(in_value[0], op(in_value[1], op(..., in_value[i]) ... )). For the array variant, `out_values` contains a pointer to storage for the `n` output values. The prefix reduction occurs independently for each of the `n` values referenced by `in_values`, e.g., calling scan on an array of `n` values is like calling `scan` `n` separate times, one for each location in `in_values` and `out_values`.

Returns: | If no `out_value` parameter is provided, returns the result of prefix reduction.