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 SystemDatatype
s 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
SystemDatatype
s, the user can build various UserDatatype
s, 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
:
UserDatatype
represents a committed, ownedMPI_Datatype
DatatypeRef<'_>
represents a committed, borrowedMPI_Datatype
.- All builtin types are
DatatypeRef<'static>
- All builtin types are
UncommittedUserDatatype
represents an uncommitted, ownedMPI_Datatype
UncommittedDatatypeRef<'_>
represents an uncommitted, borrowedMPI_Datatype
Along with this, there are two traits that are applied to these types:
UncommittedDatatype
indicates the type represents a possibly uncommittedMPI_Datatype
Datatype
indicates 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
Datatype traits
Structs
A reference to an MPI data type.
An immutable dynamically-typed buffer.
A mutable dynamically-typed buffer.
A buffer with a user specified count and datatype
Adds a partitioning to an existing Buffer
so that it becomes Partitioned
Adds a partitioning to an existing BufferMut
so that it becomes Partitioned
A reference to an uncommitted, or potentially uncommitted, MPI data type.
Represents an MPI datatype that has not yet been committed. Can be used to build up more complex datatypes before committing.
A user defined MPI datatype
A buffer with a user specified count and datatype
Traits
Something that has an associated datatype
A buffer is a region in memory that starts at pointer()
and contains count()
copies of
as_datatype()
.
A mutable buffer is a region in memory that starts at pointer_mut()
and contains count()
copies of as_datatype()
.
A countable collection of things.
A Datatype describes the layout of messages in memory.
A direct equivalence exists between the implementing type and an MPI datatype
Describes how a Buffer
is partitioned by specifying the count of elements and displacement
from the start of the buffer for each partition.
A buffer that is Partitioned
A mutable buffer that is Partitioned
Provides a pointer to the starting address in memory.
Provides a mutable pointer to the starting address in memory.
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
Returns the address of the argument in a format suitable for use with datatype constructors
Type Definitions
A system datatype, e.g. MPI_FLOAT