MPI_Op_create(3)

NAME
MPI_Op_create - Create an operation for reduce and scan functions

SYNOPSIS
#include <mpi.h>
int MPI_Op_create(MPI_User_function *func, int commute, MPI_Op *op);

#include <pmpi.h>
int PMPI_Op_create(MPI_User_function *func, int commute, MPI_Op *op);

#include <mpi.h>
void MPI::Op::Init(MPI::User_function *func, bool commute);

INCLUDE 'mpif.h'
MPI_OP_CREATE(func, commute, op, ierr)
EXTERN func
INTEGER commute, op, ierr

INPUT PARAMETERS
func
    - function to call (function pointer)
commute
    - does the function commute (boolean)

OUTPUT PARAMETER
op  - new operation (handle)

DESCRIPTION
The MPI_Op_create() function is used to create a MPI_Op handle op, that can be used for reduce and scan functions from a user defined function, func. If the function commutes then commute should be set to be true. This allows extra optimization in the functions using the operator, avoiding spurious copies.

  C
The form of MPI_User_function is
typedef void MPI_User_function(void *inbuf, void *outbuf, int *len, MPI_Datatype *datatype);
inbuf
    - buffer 1 (array)
outbuf
    - buffer 2 (array)
len - buffer length in units of datatype (integer)
datatype
    - type of elements in buffer (handle)

  C++
The form is similar typedef void MPI::User_function(const void *inbuf, void *outbuf, int len, const MPI::Datatype &datatype);

  FORTRAN
MPI_User_function will take FORTRAN INTEGER handles. Unlike other FORTRAN functions, the user function does not take an ierr parameter to return an error code.

USER FUNCTIONS
The function should perform an operation on inbuf and outbuf, storing the result of that operation in outbuf. Even though len and datatype are pointers, the user function should not alter the underlying values. All user functions are assumed to be associative, which allows computation of the results in any order. This version of MPI will compute the results of a reduce or scan operation in a stable manner, not reordering operations based on process physical location. An op created by this function should eventually be freed by MPI_Op_free(). PMPI_Op_create() is the profiling version of this function.

ERRORS
All MPI routines except for MPI_Wtime and MPI_Wtick return an error code. The the current MPI error handler is invoked if the return value is not MPI_SUCCESS. The default error handler aborts, but this may be changed with by using the MPI_Errhandler_set() function. The predefined error handler MPI_ERRORS_RETURN may be used to cause error values to be returned instead. Note that MPI does not guarentee that an MPI program can continue past an error. In this implementation, all errors except MPI_ERR_INTERN or MPI_ERR_OTHER should always be recoverable. In C, the error code is passed as the return value. In FORTRAN, all functions have an parameter ierr which returns the error code. MPI C++ functions do not directly return an error code. However, C++ users may want to use the MPI::ERRORS_THROW_EXCEPTIONS handler. This will throw an MPI::Exception with the corresponding error code. To prevent exceptions from being raised from within C and Fortran code, they will see all error return values as MPI_ERR_PENDING when this handler is chosen. In this implementation, call MPI::throw_exception() to throw the correct exception if this occurs.
MPI_SUCCESS
    - No error;
MPI_ERR_PENDING
    - Pending exception;
MPI_ERR_ARG
    - Invalid pointer;
MPI_ERR_INTERN
    - Out of memory.

SEE ALSO
MPI_Op_free(3), MPI_Reduce(3), MPI_Allreduce(3), MPI_Reduce_scatter(3), MPI_Scan(3), MPI_Exscan(3)