The procedures that add and remove error classes, codes, or strings are thread-safe, as defined in Section MPI and Threads. They are some of the few MPI procedures that may be called before MPI is initialized or after MPI is finalized, as defined in Section MPI Functionality that is Always Available.
Advice to users.
Note that despite the procedures being thread-safe, some concurrent calls can result
in undefined behavior. Notably, the rules mandating that a call adding an error
class/code/string must precede a call that removes that error class/code/string apply even
when the procedures are called from different threads. Calling the procedures with different
input values for the class/code parameters is always thread-safe.
( End of advice to users.)
| MPI_ADD_ERROR_CLASS(errorclass) | |
| OUT errorclass | value for the new error class (integer) |
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 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. 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 a constant value and
is not affected by new user-defined
error codes and classes.
Instead, when using the World Model (Section The World Model), 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
procedure to explicitly add or remove an error class/code. In a multithreaded
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_REMOVE_ERROR_CLASS(errorclass) | |
| IN errorclass | value for the error class to remove (integer) |
Removes a user-created error class.
The value of the predefined attribute key MPI_LASTUSEDCODE associated with MPI_COMM_WORLD is updated to reflect the maximum error class value. Note that there may be unused error classes that have a smaller value than MPI_LASTUSEDCODE.
It is erroneous to call MPI_REMOVE_ERROR_CLASS with a value for errorclass that was not added by a call to MPI_ADD_ERROR_CLASS. Once an errorclass is removed by calling MPI_REMOVE_ERROR_CLASS, it is erroneous to remove it again without first obtaining the value from another call to MPI_ADD_ERROR_CLASS. It is erroneous to remove an error class when its associated error codes have not been removed before.
| MPI_ADD_ERROR_CODE(errorclass, errorcode) | |
| IN errorclass | error class (integer) |
| OUT errorcode | new error code to be associated with errorclass (integer) |
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.)
| MPI_REMOVE_ERROR_CODE(errorcode) | |
| IN errorcode | error code to be removed (integer) |
Removes a user-created error code and all its associations with any error class.
It is erroneous to call MPI_REMOVE_ERROR_CODE with a value for errorcode that was not added by a call to MPI_ADD_ERROR_CODE. Once an errorcode is removed by calling MPI_REMOVE_ERROR_CODE, it is erroneous to remove it again without first obtaining the value from another call to MPI_ADD_ERROR_CODE. It is erroneous to remove an error code when its associated error string has not been removed before.
| MPI_ADD_ERROR_STRING(errorcode, string) | |
| IN errorcode | error code or class (integer) |
| IN string | text corresponding to errorcode (string) |
Associates a user-defined 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. 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 ≥ errorMPI_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).
| MPI_REMOVE_ERROR_STRING(errorcode) | |
| IN errorcode | error code or class (integer) |
Removes a user-defined association of an error string with an error code or class.
It is erroneous to call MPI_REMOVE_ERROR_STRING with a value for errorcode that does not have an error string added by a call to MPI_ADD_ERROR_STRING.