OpenMPI  0.1.1
errhandler.h File Reference
#include "ompi_config.h"
#include "mpi.h"
#include "opal/prefetch.h"
#include "opal/class/opal_object.h"
#include "opal/class/opal_pointer_array.h"
#include "ompi/runtime/mpiruntime.h"
#include "ompi/errhandler/errhandler_predefined.h"
#include "ompi/errhandler/errcode-internal.h"
#include "orte/types.h"

Go to the source code of this file.

Data Structures

struct  ompi_errhandler_t
 Back-end type for MPI_Errorhandler. More...
 
struct  ompi_predefined_errhandler_t
 

Macros

#define PREDEFINED_ERRHANDLER_PAD   1024
 Padded struct to maintain back compatibiltiy. More...
 
#define OMPI_ERR_INIT_FINALIZE(name)
 This is the macro to check the state of MPI and determine whether it was properly initialized and not yet finalized. More...
 
#define OMPI_ERRHANDLER_INVOKE(mpi_object, err_code, message)
 This is the macro to invoke to directly invoke an MPI error handler. More...
 
#define OMPI_ERRHANDLER_CHECK(rc, mpi_object, err_code, message)
 Conditionally invoke an MPI error handler. More...
 
#define OMPI_ERRHANDLER_RETURN(rc, mpi_object, err_code, message)
 Conditionally invoke an MPI error handler; if there is no error, return MPI_SUCCESS. More...
 

Typedefs

typedef void( ompi_errhandler_fortran_handler_fn_t )(MPI_Fint *, MPI_Fint *,...)
 Typedef for all fortran errhandler functions.
 
typedef void( ompi_errhandler_generic_handler_fn_t )(void *, int *,...)
 Typedef for generic errhandler function.
 
typedef enum ompi_errhandler_lang_t ompi_errhandler_lang_t
 
typedef enum ompi_errhandler_type_t ompi_errhandler_type_t
 
typedef void( ompi_errhandler_cxx_dispatch_fn_t )(struct ompi_errhandler_t *errhandler, void *handle, int *err_code, const char *message)
 C++ invocation function signature.
 
typedef struct ompi_errhandler_t ompi_errhandler_t
 
typedef struct
ompi_predefined_errhandler_t 
ompi_predefined_errhandler_t
 

Enumerations

enum  { OMPI_ERRHANDLER_NULL_FORTRAN = 0, OMPI_ERRORS_ARE_FATAL_FORTRAN, OMPI_ERRORS_RETURN_FORTRAN }
 
enum  ompi_errhandler_lang_t { OMPI_ERRHANDLER_LANG_C, OMPI_ERRHANDLER_LANG_CXX, OMPI_ERRHANDLER_LANG_FORTRAN }
 Enum to denote what language the error handler was created from.
 
enum  ompi_errhandler_type_t { OMPI_ERRHANDLER_TYPE_PREDEFINED, OMPI_ERRHANDLER_TYPE_COMM, OMPI_ERRHANDLER_TYPE_WIN, OMPI_ERRHANDLER_TYPE_FILE }
 Enum used to describe what kind MPI object an error handler is used for.
 

Functions

int ompi_errhandler_init (void)
 Initialize the error handler interface. More...
 
int ompi_errhandler_finalize (void)
 Finalize the error handler interface. More...
 
OMPI_DECLSPEC int ompi_errhandler_invoke (ompi_errhandler_t *errhandler, void *mpi_object, int type, int err_code, const char *message)
 
int ompi_errhandler_request_invoke (int count, struct ompi_request_t **requests, const char *message)
 Invoke an MPI exception on the first request found in the array that has a non-MPI_SUCCESS value for MPI_ERROR in its status. More...
 
OMPI_DECLSPEC ompi_errhandler_tompi_errhandler_create (ompi_errhandler_type_t object_type, ompi_errhandler_generic_handler_fn_t *func, ompi_errhandler_lang_t language)
 Create a ompi_errhandler_t. More...
 
OMPI_DECLSPEC void ompi_errhandler_runtime_callback (opal_pointer_array_t *procs)
 Callback function from runtime layer to alert the MPI layer of an error at the runtime layer. More...
 
static bool ompi_errhandler_is_intrinsic (ompi_errhandler_t *errhandler)
 Check to see if an errhandler is intrinsic. More...
 

Variables

OMPI_DECLSPEC
ompi_predefined_errhandler_t 
ompi_mpi_errhandler_null
 Global variable for MPI_ERRHANDLER_NULL.
 
OMPI_DECLSPEC
ompi_predefined_errhandler_t 
ompi_mpi_errors_are_fatal
 Global variable for MPI_ERRORS_ARE_FATAL.
 
OMPI_DECLSPEC
ompi_predefined_errhandler_t 
ompi_mpi_errors_return
 Global variable for MPI_ERRORS_RETURN.
 
OMPI_DECLSPEC
ompi_predefined_errhandler_t 
ompi_mpi_errors_throw_exceptions
 Global variable for MPI::ERRORS_THROW_EXCEPTIONS. More...
 
OMPI_DECLSPEC opal_pointer_array_t ompi_errhandler_f_to_c_table
 Table for Fortran <-> C errhandler handle conversion.
 

Macro Definition Documentation

#define OMPI_ERR_INIT_FINALIZE (   name)
Value:
if( OPAL_UNLIKELY(!ompi_mpi_initialized || ompi_mpi_finalized) ) { \
ompi_mpi_errors_are_fatal_comm_handler(NULL, NULL, name); \
}
OMPI_DECLSPEC bool ompi_mpi_finalized
Has mpi been finalized?
Definition: ompi_mpi_init.c:124
OMPI_DECLSPEC bool ompi_mpi_initialized
Is mpi initialized?
Definition: ompi_mpi_init.c:123

This is the macro to check the state of MPI and determine whether it was properly initialized and not yet finalized.

This macro directly invokes the ompi_mpi_errors_are_fatal_handler() when an error occurs because MPI_COMM_WORLD does not exist (because we're before MPI_Init() or after MPI_Finalize()).

#define OMPI_ERRHANDLER_CHECK (   rc,
  mpi_object,
  err_code,
  message 
)
Value:
if( OPAL_UNLIKELY(rc != OMPI_SUCCESS) ) { \
int __mpi_err_code = ompi_errcode_get_mpi_code(err_code); \
OPAL_CR_EXIT_LIBRARY() \
ompi_errhandler_invoke((mpi_object)->error_handler, \
(mpi_object), \
(int) (mpi_object)->errhandler_type, \
(__mpi_err_code), \
(message)); \
return (__mpi_err_code); \
}
static int ompi_errcode_get_mpi_code(int errcode)
Return the MPI errcode for a given internal error code.
Definition: errcode-internal.h:57

Conditionally invoke an MPI error handler.

Parameters
rcThe return code to check
mpi_objectThe MPI object to invoke the errhandler on (a comm, win, or win)
err_codeThe error code
messageAny additional message; typically the name of the MPI function that is invoking the error.

This macro will invoke the error handler if the return code is not OMPI_SUCCESS.

#define OMPI_ERRHANDLER_INVOKE (   mpi_object,
  err_code,
  message 
)
Value:
ompi_errhandler_invoke((mpi_object)->error_handler, \
(mpi_object), \
(int)(mpi_object)->errhandler_type, \
(message));
static int ompi_errcode_get_mpi_code(int errcode)
Return the MPI errcode for a given internal error code.
Definition: errcode-internal.h:57

This is the macro to invoke to directly invoke an MPI error handler.

Parameters
mpi_objectThe MPI object to invoke the errhandler on (a comm, win, or win)
err_codeThe error code
messageAny additional message; typically the name of the MPI function that is invoking the error.

This macro is used when you want to directly invoke the error handler. It is exactly equivalent to calling ompi_errhandler_invoke() directly, but is provided to have a parallel invocation to OMPI_ERRHANDLER_CHECK() and OMPI_ERRHANDLER_RETURN().

#define OMPI_ERRHANDLER_RETURN (   rc,
  mpi_object,
  err_code,
  message 
)
Value:
OPAL_CR_EXIT_LIBRARY() \
if ( OPAL_UNLIKELY(OMPI_SUCCESS != rc) ) { \
int __mpi_err_code = ompi_errcode_get_mpi_code(err_code); \
ompi_errhandler_invoke((mpi_object)->error_handler, \
(mpi_object), \
(int)(mpi_object)->errhandler_type, \
(__mpi_err_code), \
(message)); \
return (__mpi_err_code); \
} else { \
return MPI_SUCCESS; \
}
static int ompi_errcode_get_mpi_code(int errcode)
Return the MPI errcode for a given internal error code.
Definition: errcode-internal.h:57

Conditionally invoke an MPI error handler; if there is no error, return MPI_SUCCESS.

Parameters
rcThe return code to check
mpi_objectThe MPI object to invoke the errhandler on (a comm, win, or win)
err_codeThe error code
messageAny additional message; typically the name of the MPI function that is invoking the error.

This macro will invoke the error handler if the return code is not OMPI_SUCCESS. If the return code is OMPI_SUCCESS, then return MPI_SUCCESS.

#define PREDEFINED_ERRHANDLER_PAD   1024

Padded struct to maintain back compatibiltiy.

See ompi/communicator/communicator.h comments with struct ompi_communicator_t for full explanation why we chose the following padding construct for predefines.

Function Documentation

OMPI_DECLSPEC ompi_errhandler_t* ompi_errhandler_create ( ompi_errhandler_type_t  object_type,
ompi_errhandler_generic_handler_fn_t func,
ompi_errhandler_lang_t  language 
)

Create a ompi_errhandler_t.

Parameters
object_typeEnum of the type of MPI object
funcFunction pointer of the error handler
Returns
errhandler Pointer to the ompi_errorhandler_t that will be created and returned

This function is called as the back-end of all the MPI_*_CREATE_ERRHANDLER functions. It creates a new ompi_errhandler_t object, initializes it to the correct object type, and sets the callback function on it.

The type of the function pointer is (arbitrarily) the fortran function handler type. Since this function has to accept 4 different function pointer types (lest we have 4 different functions to create errhandlers), the fortran one was picked arbitrarily. Note that (void*) is not sufficient because at least theoretically, a sizeof(void*) may not necessarily be the same as sizeof(void(*)).

References OBJ_RELEASE.

int ompi_errhandler_finalize ( void  )

Finalize the error handler interface.

Returns
OMPI_SUCCESS Always

Invokes from ompi_mpi_finalize(); tears down the error handler interface, and destroys the F2C translation table.

References OBJ_DESTRUCT.

Referenced by ompi_mpi_finalize().

int ompi_errhandler_init ( void  )

Initialize the error handler interface.

Returns
OMPI_SUCCESS Upon success
OMPI_ERROR Otherwise

Invoked from ompi_mpi_init(); sets up the error handler interface, creates the predefined MPI errorhandlers, and creates the corresopnding F2C translation table.

References OBJ_CONSTRUCT, and opal_pointer_array_init().

Referenced by ompi_mpi_init().

static bool ompi_errhandler_is_intrinsic ( ompi_errhandler_t errhandler)
inlinestatic

Check to see if an errhandler is intrinsic.

Parameters
errhandlerThe errhandler to check
Returns
true If the errhandler is intrinsic
false If the errhandler is not intrinsic

Self-explanitory. This is needed in a few top-level MPI functions; this function is provided to hide the internal structure field names.

int ompi_errhandler_request_invoke ( int  count,
struct ompi_request_t **  requests,
const char *  message 
)

Invoke an MPI exception on the first request found in the array that has a non-MPI_SUCCESS value for MPI_ERROR in its status.

It is safe to invoke this function if none of the requests have an outstanding error; MPI_SUCCESS will be returned.

References ompi_file_t::errhandler_type, ompi_file_t::error_handler, ompi_errcode_get_mpi_code(), ompi_request_free(), ompi_request_t::req_mpi_object, and ompi_request_t::req_type.

OMPI_DECLSPEC void ompi_errhandler_runtime_callback ( opal_pointer_array_t procs)

Callback function from runtime layer to alert the MPI layer of an error at the runtime layer.

Parameters
procsThe names of the processes that have failed.

This function is used to alert the MPI layer to a specific fault at the runtime layer. Currently, the only faults reported using this method are process failures. The MPI layer has the option to perform whatever actions it needs to stabalize itself and continue running, abort, etc.

Callback function from runtime layer to alert the MPI layer of an error at the runtime layer.

References ompi_mpi_abort().

Referenced by ompi_mpi_init().

Variable Documentation

OMPI_DECLSPEC ompi_predefined_errhandler_t ompi_mpi_errors_throw_exceptions

Global variable for MPI::ERRORS_THROW_EXCEPTIONS.

Will abort if MPI_INIT wasn't called as MPI::INIT