MPI Subroutine Reference

MPI_ERRHANDLER_CREATE, MPI_Errhandler_create

Purpose

Registers a user-defined error handler.

C synopsis

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

FORTRAN synopsis

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

Parameters

function

is a user-defined error handling procedure (IN)

errhandler

is an MPI error handler (handle) (OUT)

IERROR

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

Description

This subroutine registers the user routine function for use as an MPI error handler.

You can associate an error handler with a communicator. MPI will use the specified error handling routine for any exception that takes place during a call on this communicator. Different tasks can attach different error handlers to the same communicator. MPI calls not related to a specific communicator are considered as attached to the communicator MPI_COMM_WORLD.

Notes

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

MPI not initialized

MPI already finalized

Null function not allowed

function cannot be NULL.

Related information

MPI_ERRHANDLER_FREE

MPI_ERRHANDLER_GET

MPI_ERRHANDLER_SET