10.5.2. Calling Error Handlers

PreviousUpNext
Up: Error Classes, Error Codes, and Error Handlers Next: Timers and Synchronization Previous: User-Defined Error Classes and Codes

Section Error Handling describes the methods for creating and associating error handlers with communicators, files, windows, and sessions. Error handlers can be invoked implicitly when errors are raised during MPI operations, but can also be called by the user.

MPI_COMM_CALL_ERRHANDLER(comm, errorcode)
IN commcommunicator with error handler (handle)
IN errorcodeerror code (integer)
C binding
int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode)
Fortran 2008 binding
MPI_Comm_call_errhandler(comm, errorcode, ierror)

TYPE(MPI_Comm), INTENT(IN) :: comm
INTEGER, INTENT(IN) :: errorcode
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR)

INTEGER COMM, ERRORCODE, IERROR

This function invokes the error handler assigned to the communicator with the error code supplied. This function returns MPI_SUCCESS in C and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).

MPI_WIN_CALL_ERRHANDLER(win, errorcode)
IN winwindow with error handler (handle)
IN errorcodeerror code (integer)
C binding
int MPI_Win_call_errhandler(MPI_Win win, int errorcode)
Fortran 2008 binding
MPI_Win_call_errhandler(win, errorcode, ierror)

TYPE(MPI_Win), INTENT(IN) :: win
INTEGER, INTENT(IN) :: errorcode
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR)

INTEGER WIN, ERRORCODE, IERROR

This function invokes the error handler assigned to the window with the error code supplied. This function returns MPI_SUCCESS in C and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).


Advice to users.

In contrast to communicators, the error handler MPI_ERRORS_ARE_FATAL is associated with a window when it is created. ( End of advice to users.)

MPI_FILE_CALL_ERRHANDLER(fh, errorcode)
IN fhfile with error handler (handle)
IN errorcodeerror code (integer)
C binding
int MPI_File_call_errhandler(MPI_File fh, int errorcode)
Fortran 2008 binding
MPI_File_call_errhandler(fh, errorcode, ierror)

TYPE(MPI_File), INTENT(IN) :: fh
INTEGER, INTENT(IN) :: errorcode
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)

INTEGER FH, ERRORCODE, IERROR

This function invokes the error handler assigned to the file with the error code supplied. This function returns MPI_SUCCESS in C and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).


Advice to users.

The default error handler for files is MPI_ERRORS_RETURN. ( End of advice to users.)

MPI_SESSION_CALL_ERRHANDLER(session, errorcode)
IN sessionsession with error handler (handle)
IN errorcodeerror code (integer)
C binding
int MPI_Session_call_errhandler(MPI_Session session, int errorcode)
Fortran 2008 binding
MPI_Session_call_errhandler(session, errorcode, ierror)

TYPE(MPI_Session), INTENT(IN) :: session
INTEGER, INTENT(IN) :: errorcode
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_SESSION_CALL_ERRHANDLER(SESSION, ERRORCODE, IERROR)

INTEGER SESSION, ERRORCODE, IERROR

This function invokes the error handler assigned to the session with the error code supplied. This function returns MPI_SUCCESS in C and the same value in IERROR if the error handler was successfully called (assuming the process is not aborted and the error handler returns).


Advice to users.

Users are warned that handlers should not be called recursively with MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER, MPI_WIN_CALL_ERRHANDLER, or MPI_SESSION_CALL_ERRHANDLER. Doing this can create a situation where an infinite recursion is created. This can occur if MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER, MPI_WIN_CALL_ERRHANDLER, or MPI_SESSION_CALL_ERRHANDLER is called inside an error handler.

Error codes and classes are associated with a process. As a result, they may be used in any error handler. Error handlers should be prepared to deal with any error code they are given. Furthermore, it is good practice to only call an error handler with the appropriate error codes. For example, file errors would normally be sent to the file error handler. ( End of advice to users.)


PreviousUpNext
Up: Error Classes, Error Codes, and Error Handlers Next: Timers and Synchronization Previous: User-Defined Error Classes and Codes


Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023