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