Advanced

Object handling

MPI.free — Function

MPI.free(obj)

Free the MPI object handle obj. This is typically used as the finalizer, and so need not be called directly unless otherwise noted.

source

Datatype objects

MPI.Datatype — Type

Datatype

A Datatype represents the layout of the data in memory.

Usage

Datatype(T)

Either return the predefined Datatype corresponding to T, or create a new Datatype for the Julia type T, calling Types.commit! so that it can be used for communication operations.

Note that this can only be called on types for which isbitstype(T) is true.

source

MPI.to_type — Function

to_type(datatype::Datatype)

Return the Julia type corresponding to the MPI Datatype datatype, or nothing if it doesn't correspond directly.

source

MPI.Types.extent — Function

lb, extent = MPI.Types.extent(dt::MPI.Datatype)

Gets the lowerbound lb and the extent extent in bytes.

External links

MPI_Type_get_extent man page: OpenMPI, MPICH

source

MPI.Types.create_contiguous — Function

MPI.Types.create_contiguous(count::Integer, oldtype::MPI.Datatype)

Create a derived Datatype that replicates oldtype into count contiguous locations.

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

External links

MPI_Type_contiguous man page: OpenMPI, MPICH

source

MPI.Types.create_vector — Function

MPI.Types.create_vector(count::Integer, blocklength::Integer, stride::Integer, oldtype::MPI.Datatype)

Create a derived Datatype that replicates oldtype into locations that consist of equally spaced blocks.

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

Example

datatype = MPI.Types.create_vector(3, 2, 5, MPI.Datatype(Int64))
MPI.Types.commit!(datatype)

will create a datatype with the following layout

|<----->|  block length

+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
| X | X |   |   |   | X | X |   |   |   | X | X |   |   |   |
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+

|<---- stride ----->|

where each segment represents an Int64.

(image by Jonathan Dursi, https://stackoverflow.com/a/10788351/392585)

External links

MPI_Type_vector man page: OpenMPI, MPICH

source

MPI.Types.create_hvector — Function

MPI.Types.create_hvector(count::Integer, blocklength::Integer, stride::Integer, oldtype::MPI.Datatype)

Create a derived Datatype that replicates oldtype into locations that consist of equally spaced (bytes) blocks.

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

Example

datatype = MPI.Types.create_hvector(3, 2, 5, MPI.Datatype(Int64))
MPI.Types.commit!(datatype)

External links

MPI_Type_create_hvector man page: OpenMPI, MPICH

source

MPI.Types.create_subarray — Function

MPI.Types.create_subarray(sizes, subsizes, offset, oldtype::Datatype;
                          rowmajor=false)

Creates a derived Datatype describing an N-dimensional subarray of size subsizes of an N-dimensional array of size sizes and element type oldtype, with the first element offset by offset (i.e. the 0-based index of the first element).

Column-major indexing (used by Julia and Fortran) is assumed; use the keyword rowmajor=true to specify row-major layout (used by C and numpy).

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

External links

MPI_Type_create_subarray man page: OpenMPI, MPICH

source

MPI.Types.create_struct — Function

MPI.Types.create_struct(blocklengths, displacements, types)

Creates a derived Datatype describing a struct layout.

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

External links

MPI_Type_create_struct man page: OpenMPI, MPICH

source

MPI.Types.create_resized — Function

MPI.Types.create_resized(oldtype::Datatype, lb::Integer, extent::Integer)

Creates a new Datatype that is identical to oldtype, except that the lower bound of this new datatype is set to be lb, and its upper bound is set to be lb + extent.

Note that MPI.Types.commit! must be used before the datatype can be used for communication.

See also

MPI.Types.extent

External links

MPI_Type_create_resized man page: OpenMPI, MPICH

source

MPI.Types.commit! — Function

MPI.Types.commit!(newtype::Datatype)

Commits the Datatype newtype so that it can be used for communication. Returns newtype.

External links

MPI_Type_commit man page: OpenMPI, MPICH

source

MPI.Types.duplicate — Function

MPI.Types.duplicate(oldtype::Datatype)

Duplicates the datatype oldtype.

External links

MPI_Type_dup man page: OpenMPI, MPICH

source

Operator objects

MPI.Op — Type

Op

An MPI reduction operator, for use with Reduce/Scan collective operations to wrap binary operators. MPI.jl will perform this conversion automatically.

Usage

Op(op, T=Any; iscommutative=false)

Wrap the Julia reduction function op for arguments of type T. op is assumed to be associative, and if iscommutative is true, assumed to be commutative as well.

See also

source

MPI.@RegisterOp — Macro

@RegisterOp(f, T)

Register a custom operator Op using the function f statically. On platfroms like AArch64, Julia does not support runtime closures, being passed to C. The generic version of Op uses runtime closures to support arbitrary functions being passed as MPI reduction operators. @RegisterOp statically adds a function to the set of functions allowed as as an MPI operator.

function my_reduce(x, y)
    2x+y-x
end
MPI.@RegisterOp(my_reduce, Int)
# ...
MPI.Reduce!(send_arr, recv_arr, my_reduce, MPI.COMM_WORLD; root=root)
#...

Warning

Note that @RegisterOp works be introducing a new method of the generic function Op. It can only be used as a top-level statement and may trigger method invalidations.

Note

T can be Any, but this will lead to a runtime dispatch.

source

Info objects

MPI.Info — Type

Info <: AbstractDict{Symbol,String}

MPI.Info objects store key-value pairs, and are typically used for passing optional arguments to MPI functions.

Usage

These will typically be hidden from user-facing APIs by splatting keywords, e.g.

function f(args...; kwargs...)
    info = Info(kwargs...)
    # pass `info` object to `ccall`
end

For manual usage, Info objects act like Julia Dict objects:

info = Info(init=true) # keyword argument is required
info[key] = value
x = info[key]
delete!(info, key)

If init=false is used in the constructor (the default), a "null" Info object will be returned: no keys can be added to such an object.

source

MPI.infoval — Function

infoval(x)

Convert Julia object x to a string representation for storing in an Info object.

The MPI specification allows passing strings, Boolean values, integers, and lists.

source

Error handler objects

MPI.Errhandler — Type

MPI.Errhandler

An MPI error handler object. Currently only two are supported:

ERRORS_ARE_FATAL (default): program will immediately abort
ERRORS_RETURN: program will throw an MPIError.

source

MPI.get_errorhandler — Function

MPI.get_errorhandler(comm::MPI.Comm)
MPI.get_errorhandler(win::MPI.Win)
MPI.get_errorhandler(file::MPI.File.FileHandle)

Get the current Errhandler for the relevant MPI object.

See also

set_errorhandler!

source

MPI.set_errorhandler! — Function

MPI.set_errorhandler!(comm::MPI.Comm, errh::Errhandler)
MPI.set_errorhandler!(win::MPI.Win, errh::Errhandler)
MPI.set_errorhandler!(file::MPI.File.FileHandle, errh::Errhandler)

Set the Errhandler for the relevant MPI object.

See also

get_errorhandler

source

MPI.set_default_error_handler_return — Function

MPI.set_default_error_handler_return()

Set the error handler for MPI_COMM_SELF and MPI_COMM_WORLD to MPI_ERRORS_RETURN. This will cause certain MPI errors to appear as Julia exceptions.

This function is executed automatically by MPI.Init() but may be invoked manually if MPI has been initialized externally by a direct call to MPI_Init(). It is safe to call this function multiple times.

source

Miscellaneous

MPI.API.@const_ref — Macro

@const_ref name T expr

Defines an constant binding

const name = Ref{T}()

and adds a hook to execute

name[] = expr

at module initialization time.

source