Module mpi::datatype

source ·
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:

  • UserDatatype represents a committed, owned MPI_Datatype
  • DatatypeRef<'_> represents a committed, borrowed MPI_Datatype.
    • All builtin types are DatatypeRef<'static>
  • UncommittedUserDatatype represents an uncommitted, owned MPI_Datatype
  • UncommittedDatatypeRef<'_> represents an uncommitted, borrowed MPI_Datatype

Along with this, there are two traits that are applied to these types:

  • UncommittedDatatype indicates the type represents a possibly uncommitted MPI_Datatype
  • Datatype indicates the type represents a committed MPI_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

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 Aliases