Expand description
The core function of MPI is getting data from point A to point B (where A and B are e.g. single processes, multiple processes, the filesystem, …). It offers facilities to describe that data (layout in memory, behavior under certain operators) that go beyound a start address and a number of bytes.
An MPI datatype describes a memory layout and semantics (e.g. in a collective reduce
operation). There are several pre-defined SystemDatatypes which directly correspond to Rust
primitive types, such as MPI_DOUBLE and f64. A direct relationship between a Rust type and
an MPI datatype is covered by the Equivalence trait. Starting from the
SystemDatatypes, the user can build various UserDatatypes, e.g. to describe the layout of a
struct (which should then implement Equivalence) or to intrusively describe parts of
an object in memory like all elements below the diagonal of a dense matrix stored in row-major
order.
§Derived Datatypes
Derived MPI datatypes can exist in either an “uncommitted” or “committed” state. Only “committed” datatypes can be used in MPI communication. There is a cost to committing a datatype: only a final aggregate type should be committed when building it from component derived datatypes.
In order to represent the difference between committed and uncommitted MPI_Datatype objects,
two different flavors of types representing the “committed”-ness of the type are exposed.
Orthogonally, there are types representing both “owned” MPI_Datatype objects and “borrowed”
MPI_Datatype objects. This means there are four different types for MPI_Datatype:
UserDatatyperepresents a committed, ownedMPI_DatatypeDatatypeRef<'_>represents a committed, borrowedMPI_Datatype.- All builtin types are
DatatypeRef<'static>
- All builtin types are
UncommittedUserDatatyperepresents an uncommitted, ownedMPI_DatatypeUncommittedDatatypeRef<'_>represents an uncommitted, borrowedMPI_Datatype
Along with this, there are two traits that are applied to these types:
UncommittedDatatypeindicates the type represents a possibly uncommittedMPI_DatatypeDatatypeindicates the type represents a committedMPI_Datatype
An important concept here is that all committed Datatype objects are also
UncommittedDatatype objects. This may seem unintuitive at first, but as far as MPI is
concerned, “committing” a datatype is purely a promotion, enabling more capabilities. This
allows Datatype and UncommittedDatatype objects to be used interchangeably in the same
Datatype constructors.
For more information on derived datatypes, see section 4.1 of the MPI 3.1 Standard.
§Data Buffers
A Buffer describes a specific piece of data in memory that MPI should operate on. In addition
to specifying the datatype of the data. It knows the address in memory where the data begins
and how many instances of the datatype are contained in the data. The Buffer trait is
implemented for slices that contain types implementing Equivalence.
In order to use arbitrary datatypes to describe the contents of a slice, the View type is
provided. However, since it can be used to instruct the underlying MPI implementation to
rummage around arbitrary parts of memory, its constructors are currently marked unsafe.
§Unfinished features
- 4.1.3: Subarray datatype constructors,
MPI_Type_create_subarray(), - 4.1.4: Distributed array datatype constructors,
MPI_Type_create_darray() - 4.1.5: Address and size functions,
MPI_Get_address(),MPI_Aint_add(),MPI_Aint_diff(),MPI_Type_size(),MPI_Type_size_x() - 4.1.7: Extent and bounds of datatypes:
MPI_Type_get_extent(),MPI_Type_get_extent_x(),MPI_Type_create_resized() - 4.1.8: True extent of datatypes,
MPI_Type_get_true_extent(),MPI_Type_get_true_extent_x() - 4.1.11:
MPI_Get_elements(),MPI_Get_elements_x() - 4.1.13: Decoding a datatype,
MPI_Type_get_envelope(),MPI_Type_get_contents() - 4.3: Canonical pack and unpack,
MPI_Pack_external(),MPI_Unpack_external(),MPI_Pack_external_size()
Modules§
- traits
- Datatype traits
Structs§
- Datatype
Ref - A reference to an MPI data type.
- DynBuffer
- An immutable dynamically-typed buffer.
- DynBuffer
Mut - A mutable dynamically-typed buffer.
- MutView
- A buffer with a user specified count and datatype
- Partition
- Adds a partitioning to an existing
Bufferso that it becomesPartitioned - Partition
Mut - Adds a partitioning to an existing
BufferMutso that it becomesPartitioned - Uncommitted
Datatype Ref - A reference to an uncommitted, or potentially uncommitted, MPI data type.
- Uncommitted
User Datatype - Represents an MPI datatype that has not yet been committed. Can be used to build up more complex datatypes before committing.
- User
Datatype - A user defined MPI datatype
- View
- A buffer with a user specified count and datatype
Traits§
- AsDatatype
- Something that has an associated datatype
- Buffer
- A buffer is a region in memory that starts at
pointer()and containscount()copies ofas_datatype(). - Buffer
Mut - A mutable buffer is a region in memory that starts at
pointer_mut()and containscount()copies ofas_datatype(). - Collection
- A countable collection of things.
- Datatype
- A Datatype describes the layout of messages in memory.
- Equivalence
- A direct equivalence exists between the implementing type and an MPI datatype
- Partitioned
- Describes how a
Bufferis partitioned by specifying the count of elements and displacement from the start of the buffer for each partition. - Partitioned
Buffer - A buffer that is
Partitioned - Partitioned
Buffer Mut - A mutable buffer that is
Partitioned - Pointer
- Provides a pointer to the starting address in memory.
- Pointer
Mut - Provides a mutable pointer to the starting address in memory.
- Uncommitted
Datatype - An UncommittedDatatype is a partial description of the layout of messages in memory which may not yet have been committed to an implementation-defined message format.
Functions§
- address_
of - Returns the address of the argument in a format suitable for use with datatype constructors
Type Aliases§
- System
Datatype - A system datatype, e.g.
MPI_FLOAT