Many of the routines in MPI-// take an argument info. info is an opaque object with a handle of type MPI_Info in C, MPI::Info in C++, and INTEGER in Fortran. It consists of (key,value) pairs (both key and value are strings). A key may have only one value. MPI-/ reserves several keys and requires that if an implementation uses a reserved key, it must provide the specified functionality. An implementation is not required to support these keys and may support any others not reserved by MPI-/.
If a function does not recognize a key, it will ignore it, unless otherwise specified. If an implementation recognizes a key but does not recognize the format of the corresponding value, the result is undefined.
Keys have an implementation-defined maximum length of MPI_MAX_INFO_KEY, which is at least 32 and at most 255. Values have an implementation-defined maximum length of MPI_MAX_INFO_VAL. In Fortran, leading and trailing spaces are stripped from both. Returned values will never be larger than these maximum lengths. Both key and value are case sensitive.
When it is an argument to a non-blocking routine, info is parsed before that routine returns, so that it may be modified or freed immediately after return.
When the descriptions refer to a key or value as being a boolean, an
integer, or a list, they mean the string representation of these
types. An implementation may define its own rules for how info value
strings are converted to other types, but to ensure portability, every
implementation must support the following representations. Legal
values for a boolean must include the strings ``true'' and ``false''
(all lowercase). For integers, legal values must include string
representations of decimal values of integers that are within the
range of a standard integer type in the program. (However it is
possible that not every legal integer is a legal value for a given
key.) On positive numbers, signs are optional. No space may
appear between a
or
sign and the leading digit of a number. For
comma separated lists, the string must contain legal elements
separated by commas. Leading and trailing spaces are stripped
automatically from the types of info values described above and for
each element of a comma separated list. These rules apply to all info
values of these types. Implementations are free to specify a
different interpretation for values of other info keys.
MPI_INFO_CREATE(INFO, IERROR)INTEGER INFO, IERROR
int MPI::Info::Create()
static MPI::Info
MPI_INFO_CREATE creates a new info object. The newly created object contains no key/value pairs.
MPI_INFO_SET(info, key, value)
MPI_INFO_SET(INFO, KEY, VALUE, IERROR)INTEGER INFO, IERROR
CHARACTER*(*) KEY, VALUE
int MPI::Info::Set(const char* key, const char* value)
void
MPI_INFO_SET adds the (key,value) pair to info, and overrides the value if a value for the same key was previously set. key and value are null-terminated strings in C. In Fortran, leading and trailing spaces in key and value are stripped. If either key or value are larger than the allowed maximums, the errors MPI_ERR_INFO_KEY or MPI_ERR_INFO_VALUE are raised, respectively.
MPI_INFO_DELETE(INFO, KEY, IERROR)INTEGER INFO, IERROR
CHARACTER*(*) KEY
int MPI::Info::Delete(const char* key)
void
MPI_INFO_DELETE deletes a (key,value) pair from info. If key is not defined in info, the call raises an error of class MPI_ERR_INFO_NOKEY.
MPI_INFO_GET(info, key, valuelen, value, flag)
MPI_INFO_GET(INFO, KEY, VALUELEN, VALUE, FLAG, IERROR)INTEGER INFO, VALUELEN, IERROR
CHARACTER*(*) KEY, VALUE
LOGICAL FLAG
int MPI::Info::Get(const char* key, int valuelen, char* value) const
bool
This function retrieves the value associated with key in a previous call to MPI_INFO_SET. If such a key exists, it sets flag to true and returns the value in value, otherwise it sets flag to false and leaves value unchanged. valuelen is the number of characters available in value. If it is less than the actual size of the value, the value is truncated. In C, valuelen should be one less than the amount of allocated space to allow for the null terminator.
If key is larger than MPI_MAX_INFO_KEY, the call is erroneous.
MPI_INFO_GET_VALUELEN(info, key, valuelen, flag)
MPI_INFO_GET_VALUELEN(INFO, KEY, VALUELEN, FLAG, IERROR)INTEGER INFO, VALUELEN, IERROR
LOGICAL FLAG
CHARACTER*(*) KEY
int MPI::Info::Get_valuelen(const char* key, int& valuelen) const
bool
Retrieves the length of the value associated with key. If key is defined, valuelen is set to the length of its associated value and flag is set to true. If key is not defined, valuelen is not touched and flag is set to false. The length returned in C or C++ does not include the end-of-string character.
If key is larger than MPI_MAX_INFO_KEY, the call is erroneous.
MPI_INFO_GET_NKEYS(info, nkeys)
MPI_INFO_GET_NKEYS(INFO, NKEYS, IERROR)INTEGER INFO, NKEYS, IERROR
int MPI::Info::Get_nkeys() const
int
MPI_INFO_GET_NKEYS returns the number of currently defined keys in info.
MPI_INFO_GET_NTHKEY(info, n, key)
MPI_INFO_GET_NTHKEY(INFO, N, KEY, IERROR)INTEGER INFO, N, IERROR
CHARACTER*(*) KEY
int MPI::Info::Get_nthkey(int n, char* key) const
void
This function returns the nth defined key in info.
Keys are numbered where
is the
value returned by MPI_INFO_GET_NKEYS.
All keys between
and
are guaranteed to
be defined. The number of a given key does not change
as long as info is not modified with
MPI_INFO_SET or MPI_INFO_DELETE.
MPI_INFO_DUP(INFO, NEWINFO, IERROR)INTEGER INFO, NEWINFO, IERROR
int MPI::Info::Dup() const
MPI::Info
MPI_INFO_DUP duplicates an existing info object, creating a new object, with the same (key,value) pairs and the same ordering of keys.
MPI_INFO_FREE(INFO, IERROR) INTEGER INFO, IERROR
int MPI::Info::Free()
void
This function frees info and sets it to MPI_INFO_NULL. The value of an info argument is interpreted each time the info is passed to a routine. Changes to an info after return from a routine do not affect that interpretation.
MPI-Standard for MARMOT