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:
| 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 leq constiMPI_ERR_LASTCODE.
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.)