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 MPI, see Chapter I/O on page I/O . 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() (binding deprecated, see Section Deprecated since MPI-2.2
) }
Creates a new error class and returns the value for it.
To avoid conflicts with existing error codes and classes, the value is
set by the implementation and not by the user.
( End of rationale.)
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.)
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 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.)
int MPI_Add_error_code(int errorclass, int *errorcode)
MPI_ADD_ERROR_CODE(ERRORCLASS, ERRORCODE, IERROR)
{ int MPI::Add_error_code(int errorclass) (binding deprecated, see Section Deprecated since MPI-2.2
) }
Creates new error code associated with
errorclass and returns its value in errorcode.
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.)
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.)
int MPI_Add_error_string(int errorcode, char *string)
MPI_ADD_ERROR_STRING(ERRORCODE, STRING, IERROR)
{ void MPI::Add_error_string(int errorcode, const char* string) (binding deprecated, see Section Deprecated since MPI-2.2
) }
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 Handling
on
page Error Handling
describes the methods for creating
and associating error handlers with communicators, files, and windows.
int MPI_Comm_call_errhandler(MPI_Comm comm, int errorcode)
MPI_COMM_CALL_ERRHANDLER(COMM, ERRORCODE, IERROR)
{ void MPI::Comm::Call_errhandler(int errorcode) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
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).
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.)
int MPI_Win_call_errhandler(MPI_Win win, int errorcode)
MPI_WIN_CALL_ERRHANDLER(WIN, ERRORCODE, IERROR)
{ void MPI::Win::Call_errhandler(int errorcode) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
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).
As with communicators, the default error handler for windows is
MPI_ERRORS_ARE_FATAL.
( End of advice to users.)
int MPI_File_call_errhandler(MPI_File fh, int errorcode)
MPI_FILE_CALL_ERRHANDLER(FH, ERRORCODE, IERROR)
{ void MPI::File::Call_errhandler(int errorcode) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
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).
Unlike errors on communicators and windows, the default behavior for files is to have
MPI_ERRORS_RETURN.
( End of 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
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.)
Rationale.
Advice
to implementors.
Advice to users.
The value of MPI_ERR_LASTCODE
is a constant value and
is not affected by new user-defined
error codes and classes.
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.
MPI_ADD_ERROR_CODE(errorclass, errorcode) IN errorclass error class (integer) OUT errorcode new error code to associated with errorclass (integer)
INTEGER ERRORCLASS, ERRORCODE, IERROR
Rationale.
Advice
to implementors.
MPI_ADD_ERROR_STRING(errorcode, string) IN errorcode error code or class (integer) IN string text corresponding to errorcode (string)
INTEGER ERRORCODE, IERROR
CHARACTER*(*) STRING
MPI_COMM_CALL_ERRHANDLER (comm, errorcode) IN comm communicator with error handler (handle) IN errorcode error code (integer)
INTEGER COMM, ERRORCODE, IERROR
Advice to users.
MPI_WIN_CALL_ERRHANDLER (win, errorcode) IN win window with error handler (handle) IN errorcode error code (integer)
INTEGER WIN, ERRORCODE, IERROR
Advice to users.
MPI_FILE_CALL_ERRHANDLER (fh, errorcode) IN fh file with error handler (handle) IN errorcode error code (integer)
INTEGER FH, ERRORCODE, IERROR
Advice to users.
Advice to users.
Up: Contents
Next: Timers and Synchronization
Previous: Error Codes and Classes
Return to MPI-2.2 Standard Index
Return to MPI Forum Home Page
(Unofficial) MPI-2.2 of September 4, 2009
HTML Generated on September 10, 2009