I have introduced two new typedefs in the C bindings which may need
to be changed/propagated
1) MPI_Handle_type
This replaces the void * which we have been using for handles
everywhere.
2) MPI_Handle_enum
This is the set of constants which let you tell what the type of a
handle is.
I think we voted for 1) and we clearly need 2) for the generalised
cacheing proposal. (I've made it a typedef so that systems which
support enums can use an enum. Others can just typedef it to int and
use #define as before). It's clearly an INTEGER in Fortran.
-- Jim
James Cownie
BBN UK Ltd
Phone : +44 117 9071438
E-Mail: jcownie@bbn.com
Naming Objects
There are many occasions on which it would be useful to allow a user
to associate a print name with an MPI communicator or other handle,
for instance error reporting, debugging, profiling, and so on.
This objective can be achieved using the following two functions
MPI_HANDLE_SET_NAME (handle, handletype, name)
handle The handle whose name is to be set
handletype The type of the handle argument
name The character string which is remembered as the name
int MPI_Handle_set_name(MPI_Handle_type handle, MPI_Handle_enum handletype, char *name)
SUBROUTINE MPI_HANDLE_SET_NAME(HANDLE, HANDLETYPE, NAME, IERR)
INTEGER HANDLE, HANDLETYPE
CHARACTER*(*) NAME
INTEGER IERR
MPI_HANDLE_GET_NAME (handle, handletype, name)
handle The handle whose name is to be returned
handletype The type of the handle argument
name The name previously stored on the handle, or a
null string if no such name exists
int MPI_Handle_get_name(MPI_Handle_type handle, MPI_Handle_enum handletype, char **name)
SUBROUTINE MPI_HANDLE_GET_NAME(HANDLE, HANDLETYPE, NAME, IERR)
INTEGER HANDLE, HANDLETYPE
CHARACTER*(*) NAME
INTEGER IERR
MPI_HANDLE_SET_NAME allows a user to associate a name string with a
handle. The character string which is passed to MPI_HANDLE_SET_NAME
will be saved inside the MPI library (so can be freed by the caller
immediately after the call, or allocated on the stack).
MPI_HANDLE_GET_NAME returns any name which had previously been
associated with the given handle. (Note that in the C binding it
returns a pointer to the internal copy of the name, which should not
be modified by the user, and which will become invalid should the name
be altered (e.g. by another call to MPI_HANDLE_SET_NAME, or by the
handle being deleted).
If the user has not associated a name with a handle, or an error
occurs, MPI_HANDLE_GET_NAME will return a null string (all spaces
in Fortran, "" in C), or, if the handle refers to a system
created handle such as MPI_COMM_WORLD, a suitable print string
(e.g. "MPI_COMM_WORLD"). Similarly, an implementation could
choose to set the name on an MPI_FILE handle to that of the file
which was opened on the handle. The fact that the system may have
chosen to give a default name to a handle does not prevent the user
from setting a name on the same handle, doing this removes the old
name and assigns the new one.
Rationale:
We provide separate functions for setting and getting the name of a
handle, rather than simply providing a pre-defined attribute key
for the following reasons
* It is not in general possible to store a string as an attribute
from Fortran.
* It is not easy to set up the delete function for a string attribute
unless it is known to have been allocated in the heap.
* To make the attribute key useful additional code to call
strdup is necessary. If this is not standardised then users have
to write it. This is extra unneeded work which we can easily
eliminate.
* The Fortran binding is not trivial to write (it will depend on
details of the Fortran compilation system), and will not be
portable. Therefore it should be in the library rather than in user
code.
Advice to users
The above definition means that it is safe simply to print the string
returned by MPIHANDLEGETNAME, as it is always a valid string even if
there was no name.
Note that associating a name with a handle has no effect on the
semantics of an MPI program, and will (necessarily) marginally
increase the store requirement of the program, since the names must be
saved. Therefore there is no requirement that names be associated with
handles. However debugging and profiling MPI applications may be made
easier if names are associated with communicators and other handles,
since the debugger or profiler should then be able to present
information in a less cryptic manner.