MPI Subroutine Reference

MPI_COMM_CREATE_ERRHANDLER, MPI_Comm_create_errhandler

Purpose

Creates an error handler that can be attached to communicators.

C synopsis

#include <mpi.h>
int MPI_Comm_create_errhandler (MPI_Comm_errhandler_fn *function,
                                MPI_Errhandler *errhandler);

C++ synopsis

#include mpi.h
static MPI::Errhandler MPI::Comm::Create_errhandler(MPI::Comm::Errhandler_fn* function);

FORTRAN synopsis

include 'mpif.h' or use mpi
MPI_COMM_CREATE_ERRHANDLER(EXTERNAL FUNCTION, INTEGER ERRHANDLER,
                           INTEGER IERROR)

Parameters

function

is the user-defined error handling procedure (function) (IN)

errhandler

is the MPI error handler (handle) (OUT)

IERROR

is the FORTRAN return code. It is always the last argument.

Description

In C, the user subroutine should be a function of type MPI_Comm_errhandler_fn, which is defined as:

typedef void MPI_Comm_errhandler_fn(MPI_Comm *, int *, ...);

The first argument is the communicator in use, the second is the error code to be returned.

In C++, the user subroutine should be of the form:

typedef void MPI::Comm::Errhandler_fn(MPI::Comm &, int *, ...);

In FORTRAN, the user subroutine should be of the form:

SUBROUTINE COMM_ERRHANDLER_FN(COMM, ERROR_CODE, ...)
INTEGER COMM, ERROR_CODE

Notes

MPI_COMM_CREATE_ERRHANDLER supersedes MPI_ERRHANDLER_CREATE.

The MPI standard specifies a varargs error handler prototype. A correct user error handler would be coded as:

void my_handler(MPI_Comm *comm, int *errcode, ...){}

PE MPI passes additional arguments to an error handler. The MPI standard allows this and urges an MPI implementation that does so to document the additional arguments. These additional arguments will be ignored by fully portable user error handlers. Anyone who wants to use the extra errhandler arguments can do so by using the C varargs (or stdargs) facility, but will be writing code that does not port cleanly to other MPI implementations, which happen to have different additional arguments.

The effective prototype for an error handler in PE MPI is:

typedef void (MPI_Handler_function)
  (MPI_Comm *comm, int *code, char *routine_name, int *flag,
   MPI_Aint *badval)

The additional arguments are:

routine_name

the name of the MPI routine in which the error occurred

flag

true if badval is meaningful, otherwise false

badval

the non-valid integer or long value that triggered the error

The interpretation of badval is context-dependent, so badval is not likely to be useful to a user error handler function that cannot identify this context. The routine_name string is more likely to be useful.

Errors

Fatal errors:

MPI not initialized

MPI already finalized

Null function not allowed

function cannot be NULL.

Related information

MPI_COMM_CALL_ERRHANDLER

MPI_COMM_GET_ERRHANDLER

MPI_COMM_SET_ERRHANDLER

MPI_ERRHANDLER_CREATE

MPI_ERRHANDLER_FREE