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 stores an unordered set of ( key, value) pairs (both key and value are strings). A key can 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.
An implementation must support info objects as caches for arbitrary ( key, value) pairs, regardless of whether it recognizes the key. Each function that takes hints in the form of an MPI_Info must be prepared to ignore any key it does not recognize. This description of info objects does not attempt to define how a particular function should react if it recognizes a key but not the associated value. MPI_INFO_GET_NKEYS, MPI_INFO_GET_NTHKEY, MPI_INFO_GET_VALUELEN, and MPI_INFO_GET must retain all ( key, value) pairs so that layered functionality can also use the Info object. 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.
Rationale.
Keys have a maximum length because the set of known keys will always
be finite and known to the implementation and because there is no
reason for keys to be complex. The small maximum size allows
applications to declare keys of size MPI_MAX_INFO_KEY.
The limitation on value sizes is so that an implementation is not
forced to deal with arbitrarily long
strings.
( End of rationale.)
Advice to users.
MPI_MAX_INFO_VAL might be very large, so it
might not be wise to declare a string of that size.
( End of advice to users.)
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 creates a new info object. The newly created object contains
no key/value pairs.
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 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.
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.
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 returns the number of currently defined keys in info.
This function returns the nth defined key in info.
Keys are numbered 0 ... N-1 where N is the
value returned by MPI_INFO_GET_NKEYS.
All keys between 0 and N-1 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 duplicates an existing info object, creating a new
object, with the same ( key, value) pairs and the same ordering of keys.
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.
When it is an argument to a nonblocking routine, info
is parsed before that routine returns, so that it may
be modified or freed immediately after return.
int MPI_Info_create(MPI_Info *info) MPI_INFO_CREATE(info) OUT info info object created (handle)
MPI_INFO_CREATE(INFO, IERROR)
INTEGER INFO, IERROR
{ static MPI::Info MPI::Info::Create() (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_set(MPI_Info info, char *key, char *value) MPI_INFO_SET(info, key, value) INOUT info info object (handle) IN key key (string) IN value value (string)
MPI_INFO_SET(INFO, KEY, VALUE, IERROR)
INTEGER INFO, IERROR
CHARACTER*(*) KEY, VALUE
{ void MPI::Info::Set(const char* key, const char* value) (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_delete(MPI_Info info, char *key) MPI_INFO_DELETE(info, key) INOUT info info object (handle) IN key key (string)
MPI_INFO_DELETE(INFO, KEY, IERROR)
INTEGER INFO, IERROR
CHARACTER*(*) KEY
{ void MPI::Info::Delete(const char* key) (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_get(MPI_Info info, char *key, int valuelen, char *value, int *flag) MPI_INFO_GET(info, key, valuelen, value, flag) IN info info object (handle) IN key key (string) IN valuelen length of value arg (integer) OUT value value (string) OUT flag true if key defined, false if not (boolean)
MPI_INFO_GET(INFO, KEY, VALUELEN, VALUE, FLAG, IERROR)
INTEGER INFO, VALUELEN, IERROR
CHARACTER*(*) KEY, VALUE
LOGICAL FLAG
{ bool MPI::Info::Get(const char* key, int valuelen, char* value) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_get_valuelen(MPI_Info info, char *key, int *valuelen, int *flag) MPI_INFO_GET_VALUELEN(info, key, valuelen, flag) IN info info object (handle) IN key key (string) OUT valuelen length of value arg (integer) OUT flag true if key defined, false if not (boolean)
MPI_INFO_GET_VALUELEN(INFO, KEY, VALUELEN, FLAG, IERROR)
INTEGER INFO, VALUELEN, IERROR
LOGICAL FLAG
CHARACTER*(*) KEY
{ bool MPI::Info::Get_valuelen(const char* key, int& valuelen) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_get_nkeys(MPI_Info info, int *nkeys) MPI_INFO_GET_NKEYS(info, nkeys) IN info info object (handle) OUT nkeys number of defined keys (integer)
MPI_INFO_GET_NKEYS(INFO, NKEYS, IERROR)
INTEGER INFO, NKEYS, IERROR
{ int MPI::Info::Get_nkeys() const (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_get_nthkey(MPI_Info info, int n, char *key) MPI_INFO_GET_NTHKEY(info, n, key) IN info info object (handle) IN n key number (integer) OUT key key (string)
MPI_INFO_GET_NTHKEY(INFO, N, KEY, IERROR)
INTEGER INFO, N, IERROR
CHARACTER*(*) KEY
{ void MPI::Info::Get_nthkey(int n, char* key) const (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_dup(MPI_Info info, MPI_Info *newinfo) MPI_INFO_DUP(info, newinfo) IN info info object (handle) OUT newinfo info object (handle)
MPI_INFO_DUP(INFO, NEWINFO, IERROR)
INTEGER INFO, NEWINFO, IERROR
{ MPI::Info MPI::Info::Dup() const (binding deprecated, see Section Deprecated since MPI-2.2
) }
int MPI_Info_free(MPI_Info *info) MPI_INFO_FREE(info) INOUT info info object (handle)
MPI_INFO_FREE(INFO, IERROR)
INTEGER INFO, IERROR
{ void MPI::Info::Free() (binding deprecated, see Section Deprecated since MPI-2.2
) }
Up: Contents
Next: Process Creation and Management
Previous: Portable MPI Process Startup
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