. that MPI_Type_elements now contains one additional argument --
'combiner'.
. that some predefined constants are specified (possible values
for 'combiner').
The first two functions mentioned below (MPI_Type_count and
MPI_Type_elements) have now been implemented.
Additionally, for testing purposes I have implemented a function
'print_mpi_datatype' which prints MPI datatypes using a slight variation
on the BNF syntax given in Section 3.5 "Proposal of Leslie Hart and Tom
Henderson" of the August 7, 1995 draft of "MPI-2: Extensions to the
Message-Passing Interface". This function will be described in a
separate e-mail message.]
There are useful packages that could be implemented to "supplement" or
"fill out" MPI which currently require access to internals of the MPI
implementation.
This proposal attempts to specify some of the MPI interfaces needed to
implement a portable version of the MPI-IO draft 0.3 specification.
There are three sets of MPI interfaces needed to implement an MPI-IO
which is independent of any specific implementation of MPI:
. those needed to do any I/O -- e.g., access to type maps
. those needed for efficiency -- e.g. knowing when a type is free'd
. those needed for 'immediate' i/o (the 'i' calls in MPI-IO)
The following proposed additions to MPI attempt to address the first two
of the three categories above.
[I believe that Section 3.2 "Generalized Requests" of the August 7, 1995
draft of "MPI-2: Extensions to the Message-Passing Interface" provides
the functionality needed for the third category above.]
MPI Data type accessors:
========================
MPI_TYPE_COUNT(datatype, count)
IN datatype datatype (handle)
OUT count number of entries in the datatype
int
MPI_Type_count(MPI_Datatype datatype,
int *count)
MPI_TYPE_COUNT(DATATYPE, COUNT, IERROR)
INTEGER DATATYPE, COUNT, IERROR
Returns in 'count' the number of entries in the datatype.
[i.e., as per MPI spec 1.0 except for the deletion of the words
"top-level".]
Whether this function returns the number of "top-level" entries or
"bottom-level" entries is implementation dependent. However, it
must be the same as for MPI_Type_elements (below).
[NOTE: It is preferred that "top-level" entries be returned rather than
"bottom-level" entries; does anyone know of an implementation where this
would be difficult to do?]
MPI_TYPE_ELEMENTS(datatype, count, combiner, array_of_blocklengths,
array_of_displacements, array_of_types)
IN datatype datatype (handle)
INOUT count input: how big the arrays are; output:
how many elements were actually filled in
OUT combiner top level type combiner (MPI_BASIC if
datatype is a basic type; else one of
MPI_CONTIG, MPI_VECTOR, MPI_HVECTOR,
MPI_INDEXED, MPI_HINDEXED, MPI_STRUCT
OUT array_of_blocklengths
OUT array_of_displacements
OUT array_of_types
int
MPI_Type_elements(MPI_Datatype datatype,
int *count,
int *combiner,
int *array_of_blocklengths,
MPI_Aint *array_of_displacements,
MPI_Datatype *array_of_types)
MPI_TYPE_ELEMENTS(DATATYPE, COUNT, COMBINER, ARRAY_OF_BLOCKLENGTHS,
ARRAY_OF_DISPLACEMENTS, ARRAY_OF_TYPES, IERROR)
INTEGER DATATYPE, COUNT, COMBINER, ARRAY_OF_BLOCKLENGHTS(*),
ARRAY_OF_DISPLACEMENTS(*), ARRAY_OF_TYPES(*), IERROR
Given an MPI_Datatype 'datatype', returns at most the first 'count'
block lengths, displacements, and types that make it up. The number of
items filled in is returned in 'count' (and is <= the value passed in).
Whether this function returns information about the "top-level"
entries or "bottom-level" entries is implementation dependent.
However, it must be same as for MPI_Type_count (above).
The intent here is to allow you to use the 'count' returned by
MPI_Type_count when malloc'ing the array to pass to MPI_Type_elements.
Whether you are done decomposing 'datatype' after one call to
MPI_Type_elements or you have to iterate to get to the fundamental types
is implementation dependent -- thus a correct program must iterate until
nothing is left except fundamental types.
If 'count' is less than zero, then an error is returned.
If 'count' is zero, then 'array_of_blocklengths', 'array_of_displacements',
and 'array_of_types' are not touched (and can be NULL).
For each fundamental type (see "Section 3.2.2 Message data" of MPI Spec
1.1 for a list), the type itself is returned.
The value of 'combiner' is one of the constants:
MPI_BASIC
MPI_CONTIG
MPI_VECTOR
MPI_HVECTOR
MPI_INDEXED
MPI_HINDEXED
MPI_STRUCT
Each of the above constants is a defined integer constant (C) or
parameter (FORTRAN). In C, they are usable in a switch statement.
If 'combiner' is MPI_BASIC, then the type is returned (again) in the
first element of 'array_of_types'.
If 'combiner' is MPI_CONTIG, then the count and oldtype are returned in
the first elements of 'array_of_blocklengths' and 'array_of_types'
respectively.
If 'combiner' is MPI_VECTOR or MPI_HVECTOR, then the count is returned
in 'count' and the blocklength, stride, and oldtype are returned in the
first elements of 'array_of_blocklengths', 'array_of_displacements', and
'array_of_types', respectively.
If 'combiner' is MPI_INDEXED or MPI_HINDEXED, then the count is returned
in 'count', the array_of_blocklengths and array_of_displacements are
returned in the first 'count' elements of 'array_of_blocklengths' and
'array_of_displacements' respectively, and oldtype is returned in the
first element of 'array_of_types'.
If combiner is MPI_STRUCT, then the count is returned in 'count', and
the array_of_blocklengths, array_of_displacements, and array_of_types
are returned in the first 'count' elements of 'array_of_blocklengths',
'array_of_displacements', and 'array_of_types', respectively.
MPI_Type_free Handler:
======================
[Unmodified since the previous version; included for completeness.]
For efficiency, we would like to cache some information about each
datatype. However, if we cache information, then we need some way of
knowing whether a given datatype is the same as one presented earlier.
We also want a way of knowing when the cached information is invalid and
should be thrown away.
MPI_TYPE_FREE_HANDLER(function)
IN function
typedef void (MPI_Type_handler_function)(MPI_Datatype);
int
MPI_Type_free_handler(MPI_Type_handler_function *function)
MPI_TYPE_FREE_HANDLER(FUNCTION, IERROR)
EXTERNAL FUNCTION
INTEGER IERROR
Registers the user routine 'function' as a function to be called
whenever an MPI data type is freed. Thus if a package caches
information about a type, it can know when the information is outdated.
Multiple handlers can be registered.
[Other methods of storing and retrieving the information, such as the
Proposal for Datatype and Request Caching by doss@ERC.MsState.Edu would
also work.]