---

8.5. Error Classes, Error Codes, and Error Handlers

Up: External Interfaces Next: Decoding a Datatype Previous: Naming Objects

Users may want to write a layered library on top of an existing MPI implementation, and this library may have its own set of error codes and classes. An example of such a library is an I/O library based on the I/O chapter in MPI-2. For this purpose, functions are needed to:

1. add a new error class to the ones an MPI implementation already knows.
2. associate error codes with this error class, so that MPI_ERROR_CLASS works.
3. associate strings with these error codes, so that MPI_ERROR_STRING works.
4. invoke the error handler associated with a communicator, window, or object.

Several new functions are provided to do this. They are all local. No functions are provided to free error handlers or error classes: it is not expected that an application will generate them in significant numbers.

MPI_ADD_ERROR_CLASS(errorclass)
[ OUT errorclass] value for the new error class (integer)

int MPI_Add_error_class(int *errorclass)

MPI_ADD_ERROR_CLASS(ERRORCLASS, IERROR)
INTEGER ERRORCLASS, IERROR

int MPI::Add_error_class()

Creates a new error class and returns the value for it.

[] Rationale.

To avoid conflicts with existing error codes and classes, the value is set by the implementation and not by the user. ( End of rationale.)

[] Advice to implementors.

A high quality implementation will return the value for a new errorclass in the same deterministic way on all processes. ( End of advice to implementors.)

[] Advice to users.

Since a call to MPI_ADD_ERROR_CLASS is local, the same errorclass may not be returned on all processes that make this call. Thus, it is not safe to assume that registering a new error on a set of processes at the same time will yield the same errorclass on all of the processes. However, if an implementation returns the new errorclass in a deterministic way, and they are always generated in the same order on the same set of processes (for example, all processes), then the value will be the same. However, even if a deterministic algorithm is used, the value can vary across processes. This can happen, for example, if different but overlapping groups of processes make a series of calls. As a result of these issues, getting the ``same'' error on multiple processes may not cause the same value of error code to be generated. ( End of advice to users.)
The value of MPI_ERR_LASTCODE is not affected by new user-defined error codes and classes. As in MPI-1, it is a constant value. Instead, a predefined attribute key MPI_LASTUSEDCODE is associated with MPI_COMM_WORLD. The attribute value corresponding to this key is the current maximum error class including the user-defined ones. This is a local value and may be different on different processes. The value returned by this key is always greater than or equal to MPI_ERR_LASTCODE.

[] Advice to users.

The value returned by the key MPI_LASTUSEDCODE will not change unless the user calls a function to explicitly add an error class/code. In a multi-threaded environment, the user must take extra care in assuming this value has not changed. Note that error codes and error classes are not necessarily dense. A user may not assume that each error class below MPI_LASTUSEDCODE is valid. ( End of advice to users.)
MPI_ADD_ERROR_CODE(errorclass, errorcode)
[ IN errorclass] error class (integer)
[ OUT errorcode] new error code to associated with errorclass (integer)

int MPI_Add_error_code(int errorclass, int *errorcode)

MPI_ADD_ERROR_CODE(ERRORCLASS, ERRORCODE, IERROR)
INTEGER ERRORCLASS, ERRORCODE, IERROR

int MPI::Add_error_code(int errorclass)

Creates new error code associated with errorclass and returns its value in errorcode.

[] Rationale.

To avoid conflicts with existing error codes and classes, the value of the new error code is set by the implementation and not by the user. ( End of rationale.)

[] Advice to implementors.

A high quality implementation will return the value for a new errorcode in the same deterministic way on all processes. ( End of advice to implementors.)
MPI_ADD_ERROR_STRING(errorcode, string)
[ IN errorcode] error code or class (integer)
[ IN string] text corresponding to errorcode (string)

int MPI_Add_error_string(int errorcode, char *string)

MPI_ADD_ERROR_STRING(ERRORCODE, STRING, IERROR)
INTEGER ERRORCODE, IERROR
CHARACTER*(*) STRING

void MPI::Add_error_string(int errorcode, const char* string)

Associates an error string with an error code or class. The string must be no more than MPI_MAX_ERROR_STRING characters long. The length of the string is as defined in the calling language. The length of the string does not include the null terminator in C or C++. Trailing blanks will be stripped in Fortran. Calling MPI_ADD_ERROR_STRING for an errorcode that already has a string will replace the old string with the new string. It is erroneous to call MPI_ADD_ERROR_STRING for an error code or class with a value .

If MPI_ERROR_STRING is called when no string has been set, it will return a empty string (all spaces in Fortran, "" in C and C++).

Section Error Handlers describes the methods for creating and associating error handlers with communicators, files, and windows.

MPI_COMM_CALL_ERRHANDLER (comm, errorcode)
[ IN comm] communicator with error handler (handle)
[ IN errorcode] error code (integer)

int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode)

MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR)
INTEGER COMM, ERRORCODE, IERROR

void MPI::Comm::Call_errhandler(int errorcode) const

This function invokes the error handler assigned to the communicator with the error code supplied. This function returns MPI_SUCCESS in C and 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 should note that the default error handler is MPI_ERRORS_ARE_FATAL. Thus, calling MPI_COMM_CALL_ERRHANDLER will abort the comm processes if the default error handler has not been changed for this communicator or on the parent before the communicator was created. ( End of advice to users.)
MPI_WIN_CALL_ERRHANDLER (win, errorcode)
[ IN win] window with error handler (handle)
[ IN errorcode] error code (integer)

int MPI_Win_call_errhandler(MPI_Win win, int errorcode)

MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR)
INTEGER WIN, ERRORCODE, IERROR

void MPI::Win::Call_errhandler(int errorcode) const

This function invokes the error handler assigned to the window with the error code supplied. This function returns MPI_SUCCESS in C and 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.

As with communicators, the default error handler for windows is MPI_ERRORS_ARE_FATAL. ( End of advice to users.)

MPI_FILE_CALL_ERRHANDLER (fh, errorcode)
[ IN fh] file with error handler (handle)
[ IN errorcode] error code (integer)

int MPI_File_call_errhandler(MPI_File fh, int errorcode)

MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)
INTEGER FH, ERRORCODE, IERROR

void MPI::File::Call_errhandler(int errorcode) const

This function invokes the error handler assigned to the file with the error code supplied. This function returns MPI_SUCCESS in C and 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.

Unlike errors on communicators and windows, the default behavior for files is to have MPI_ERRORS_RETURN ( End of advice to users.)

[] Advice to users.

Users are warned that handlers should not be called recursively with MPI_COMM_CALL_ERRHANDLER, MPI_FILE_CALL_ERRHANDLER, or MPI_WIN_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, or MPI_WIN_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 it is 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.)

---

Up: External Interfaces Next: Decoding a Datatype Previous: Naming Objects

---

Return to MPI-2 Standard Index

---

MPI-2.0 of July 18, 1997
HTML Generated on August 11, 1997