10.1.2. Environmental Inquiries

PreviousUpNext
Up: Implementation Information Next: Tag Values Previous: Version Inquiries

When using the World Model (Section The World Model), a set of attributes that describe the execution environment is attached to the communicator MPI_COMM_WORLD when MPI is initialized. The values of these attributes can be inquired by using the function MPI_COMM_GET_ATTR described in Section Caching and in Section Attributes. It is erroneous to delete these attributes, free their keys, or change their values.

The list of predefined attribute keys include

MPI_TAG_UB:
Upper bound for tag value.
MPI_IO:
Rank of a node that has regular I/O facilities (possibly myrank). Nodes in the same communicator may return different values for this parameter.
MPI_WTIME_IS_GLOBAL:
Boolean variable that indicates whether clocks are synchronized.

When using the Sessions Model (Section The Sessions Model), only the MPI_TAG_UB attribute is available. Vendors may add implementation-specific parameters (such as node number, real memory size, virtual memory size, etc.)

These predefined attributes do not change value between MPI initialization ( MPI_INIT) and MPI completion ( MPI_FINALIZE), and cannot be updated or deleted by users.


Advice to users.

Note that in the C binding, the value returned by these attributes is a pointer to an int containing the requested value. ( End of advice to users.)
The required parameter values are discussed in more detail below:


PreviousUpNext
Up: Implementation Information Next: Tag Values Previous: Version Inquiries


10.1.2.1. Tag Values

PreviousUpNext
Up: Environmental Inquiries Next: IO Rank Previous: Environmental Inquiries

Tag values range from 0 to the value returned for MPI_TAG_UB, inclusive. These values are guaranteed to be unchanging during the execution of an MPI program. In addition, the tag upper bound value must be at least 32767. An MPI implementation is free to make the value of MPI_TAG_UB larger than this; for example, the value 230-1 is also a valid value for MPI_TAG_UB.

In the Sessions Model, the attribute MPI_TAG_UB is attached to all communicators created by MPI_COMM_CREATE_FROM_GROUP and MPI_INTERCOMM_CREATE_FROM_GROUPS, with the same value on all MPI processes in the communicator. In the World Model, the attribute MPI_TAG_UB has the same value on all processes of MPI_COMM_WORLD.


PreviousUpNext
Up: Environmental Inquiries Next: IO Rank Previous: Environmental Inquiries


10.1.2.2. IO Rank

PreviousUpNext
Up: Environmental Inquiries Next: Clock Synchronization Previous: Tag Values

The value returned for MPI_IO is the rank of a processor that can provide language-standard I/O facilities. For Fortran, this means that all of the Fortran I/O operations are supported (e.g., OPEN, REWIND, WRITE). For C, this means that all of the ISO C I/O operations are supported (e.g., fopen, fprintf, lseek).

If every process can provide language-standard I/O, then the value MPI_ANY_SOURCE will be returned. Otherwise, if the calling process can provide language-standard I/O, then its rank will be returned. Otherwise, if some process can provide language-standard I/O then the rank of one such process will be returned. The same value need not be returned by all processes. If no process can provide language-standard I/O, then the value MPI_PROC_NULL will bereturned.


Advice to users.

Note that input is not collective, and this attribute does not indicate which process can or does provide input. ( End of advice to users.)


PreviousUpNext
Up: Environmental Inquiries Next: Clock Synchronization Previous: Tag Values


10.1.2.3. Clock Synchronization

PreviousUpNext
Up: Environmental Inquiries Next: Inquire Processor Name Previous: IO Rank

The value returned for MPI_WTIME_IS_GLOBAL is 1 if clocks at all processes in MPI_COMM_WORLD are synchronized, 0 otherwise. A collection of clocks is considered synchronized if explicit effort has been taken to synchronize them. The expectation is that the variation in time, as measured by calls to MPI_WTIME, will be less then one half the round-trip time for an MPI message of length zero. If time is measured at a process just before a send and at another process just after a matching receive, the second time should be always higher than the first one.

The attribute MPI_WTIME_IS_GLOBAL need not be present when the clocks are not synchronized (however, the attribute key MPI_WTIME_IS_GLOBAL is always valid). This attribute may be associated with communicators other then MPI_COMM_WORLD.

The attribute MPI_WTIME_IS_GLOBAL has the same value on all processes of MPI_COMM_WORLD.


PreviousUpNext
Up: Environmental Inquiries Next: Inquire Processor Name Previous: IO Rank


10.1.2.4. Inquire Processor Name

PreviousUpNext
Up: Environmental Inquiries Next: Inquire Hardware Resource Information Previous: Clock Synchronization

MPI_GET_PROCESSOR_NAME(name, resultlen)
OUT nameA unique specifier for the actual (as opposed to virtual) node.
OUT resultlenLength (in printable characters) of the result returned in name
C binding
int MPI_Get_processor_name(char *name, int *resultlen)
Fortran 2008 binding
MPI_Get_processor_name(name, resultlen, ierror)

CHARACTER(LEN=MPI_MAX_PROCESSOR_NAME), INTENT(OUT) :: name
INTEGER, INTENT(OUT) :: resultlen
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_GET_PROCESSOR_NAME(NAME, RESULTLEN, IERROR)

CHARACTER*(*) NAME
INTEGER RESULTLEN, IERROR

This routine returns the name of the processor on which it was called at the moment of the call. The name is a character string for maximum flexibility. From this value it must be possible to identify a specific piece of hardware; possible values include ``processor 9 in rack 4 of mpp.cs.org'' and ``231'' (where 231 is the actual processor number in the running homogeneous system). The argument name must represent storage that is at least MPI_MAX_PROCESSOR_NAME characters long. MPI_GET_PROCESSOR_NAME may write up to this many characters into name.

The number of characters actually written is returned in the output argument, resultlen. In C, a null character is additionally stored at name[resultlen]. The value of resultlen cannot be larger than MPI_MAX_PROCESSOR_NAME-1. In Fortran, name is padded on the right with blank characters. The value of resultlen cannot be larger than MPI_MAX_PROCESSOR_NAME.


Rationale.

This function allows MPI implementations that do process migration to return the current processor. Note that nothing in MPI requires or defines process migration; this definition of MPI_GET_PROCESSOR_NAME simply allows such an implementation. ( End of rationale.)

Advice to users.

The user must provide at least MPI_MAX_PROCESSOR_NAME space to write the processor name---processor names can be this long. The user should examine the output argument, resultlen, to determine the actual length of the name. ( End of advice to users.)


PreviousUpNext
Up: Environmental Inquiries Next: Inquire Hardware Resource Information Previous: Clock Synchronization


10.1.2.5. Inquire Hardware Resource Information

PreviousUpNext
Up: Environmental Inquiries Next: Memory Allocation Previous: Inquire Processor Name

MPI_GET_HW_RESOURCE_INFO(hw_info)
OUT hw_infoinfo object created (handle)
C binding
int MPI_Get_hw_resource_info(MPI_Info *hw_info)
Fortran 2008 binding
MPI_Get_hw_resource_info(hw_info, ierror)

TYPE(MPI_Info), INTENT(OUT) :: hw_info
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
Fortran binding
MPI_GET_HW_RESOURCE_INFO(HW_INFO, IERROR)

INTEGER HW_INFO, IERROR

MPI_GET_HW_RESOURCE_INFO is a local procedure that returns an info object containing information pertaining to the hardware platform on which the calling MPI process is executing at the moment of the call. This information is stored as ( key, value) pairs where each key is the name of a hardware resource type and its value is set to true if the calling MPI process is restricted to a single instance of a hardware resource of that type and false otherwise. The order in which the keys are stored in hw_info is unspecified. This procedure will return different information for MPI processes that are restricted to different hardware resources. Otherwise, info objects with identical ( key, value) pairs are returned. The user is responsible for freeing hw_info via MPI_INFO_FREE.

The keys stored in the hw_info object have a Uniform Resource Identifier (URI) format. The first part of the URI indicates the key provider and the second part conforms to the format used by this key provider. The key provider "mpi://" is reserved for exclusive use by the MPI standard.


Advice to implementors.

Key provider names could be derived from MPI implementation names (e.g., "mpich://", "openmpi://"), from names of external libraries or pieces of software (e.g., "hwloc://", "pmix://"), from names of programming or execution models (e.g., "openmp://"), from resource manager names (e.g., "slurm://") or from hardware vendor names. ( End of advice to implementors.)

Advice to users.

Users should be cautious when using such keys as comparisons between different providers may not be always meaningful nor relevant. ( End of advice to users.)

Advice to users.

The keys stored in the info object returned by this procedure can be used in MPI_COMM_SPLIT_TYPE with the split_type value MPI_COMM_TYPE_HW_GUIDED or MPI_COMM_TYPE_RESOURCE_GUIDED as key values for the info key mpi_hw_resource_type. ( End of advice to users.)
Subsequent calls to MPI_GET_HW_RESOURCE_INFO may return different information throughout the execution of the program because an MPI process can be relocated (e.g., migrated or have its hardware restrictions changed).


PreviousUpNext
Up: Environmental Inquiries Next: Memory Allocation Previous: Inquire Processor Name


Return to MPI-4.1 Standard Index
Return to MPI Forum Home Page

(Unofficial) MPI-4.1 of November 2, 2023
HTML Generated on November 19, 2023