MPI Module

MPI Module Overview

The HIPP::MPI module includes high-level OOP APIs that encapsulates Standard Message Passing Interface (MPI) library. It also provides non-standard extensions of MPI, which are useful in synchronization, task management and task distribution, etc.

Although the high-level APIs are always preferred to use, sometimes, user may need to go back to the oringinal MPI calls, possibly due to the demands of better performance or more flexible and detailed control of the communication behavior. The intermediate-level APIs, which is only semi-OOP, therefore provide convient tools for this purpose.

All the definitions in the MPI module can be accessed by including the header file <hippmpi.h>. Classes, functions and variables are all defined within the HIPP::MPI namespace. Code that uses the MPI module would be like

/* src.cpp */

#include <hippmpi.h>                    // include all definitions in HIPP MPI

int main(int argc, char const *argv[]){
    HIPP::MPI::Env env;                 // initialize the MPI environment
    auto world = env.world();           // the communication world object

    // use HIPP MPI to make communications
}

To generate the executable binary, the links to “libhippmpi.so” and “libhippcntl.so” are necessary. The compiling command in an Unix-like system would be like

$ mpicxx -std=c++17 src.cpp -lhippmpi -lhippcntl

To avoid confusion, we list the conventions used in this API reference:

• The term Standard means the MPI standard APIs (types, functions, variables, macros, etc.) defined by the MPI Forum . E.g. The Standard call MPI_Init() is the entrance of (almost) all Standard MPI applications.

• The HIPP MPI library has three components: the High-level API, the MPI Extensions and the Intermediate-level API (see below for the detail API references of each component). Therefore, when we say “high-level” class communicator, we mean the class HIPP::MPI::Comm in the high-level API, and when we say “extension” class Mutex, we mean the class HIPP::MPI::Mutex in the extension API.

• The documentation text of one definition would probably refer to other definitions. If they are in the same namespace (HIPP::MPI here), we drop the namespace specifiers for clarity (e.g., class Comm means class HIPP::MPI::Comm).

• The example code that uses C++ standard library may ignore the std:: namespace specifier (namely, assume a global using namespace std is used). This is not good in practice, but makes the example code more compact.

List of Module Components

All functions and classes avaiable in the HIPP MPI module is listed below. The “Standard MPI counterpart” gives the MPI type defined by the MPI standard on the top of which HIPP is built.

Functions / Classes	Standard MPI counterpart	Details
Env		MPI environment manager.
ErrMPI		Exception that is thrown on the MPI-related error.
Comm	MPI_Comm	Communicator.
Group	MPI_Group	Process group.
Requests	MPI_Request	Handler for non-blocking commnications.
Status	MPI_Status	Return status of commnications.
Datatype	MPI_Datatype	Data type which describes the data layout and representation.
Datapacket		Data buffer descriptor.
Pack		Buffers for packing/unpacking operations.
ExternalPack		Buffers for canonical packing/unpacking operations.
Op	MPI_Op	Reduction operation on data item.
Oppacket		Operation descriptor.
Win	MPI_Win	One-side commnication window.
File	MPI_File	Parallel IO handler.
Message	MPI_Message	Message object returned by probing operation.
Info	MPI_Info	Hints to the implementation.
SpinLock		Spin locks for synchronization.
Mutex		Mutual exclusion locks for synchronization.
SeqBlock		Defining operations to be sequentially executed on processes.
WorkDecomp1D		Work decomposition functions.
alloc_mem()	MPI_Alloc_mem	Memory allocation.
free_mem()	MPI_Free_mem	Memory deallocation.
buffer_attach()	MPI_Buffer_attach	Buffer attachment for buffer sending mode.
buffer_detach()	MPI_Buffer_detach	Buffer detachment for buffer sending mode.
wtime()	MPI_Wtime	Clock.
wtick()	MPI_Wtick	Clock interval.

API References

High-level API

• MPI Environment
  • Module-specific Definitions and Consts
  • Class Env: the MPI Environment manager
• Error Handling
  • Class ErrMPI: the Exception Handler
• Basic Communication
  • Class Comm: the Communication Context
  • Class Group: the Process Collection
  • Class Requests: the Non-blocking Handler
  • Class Status: the Return Status
• Datatype and Operation
  • Datatype
  • Class Datapacket
  • Class ConstDatapacket
  • Class Pack
  • Class ExternalPack
  • Class Op
  • Class Oppacket
• Remote Memory Access
  • Class Win: the RMA Window
  • Class Win::sync_guard_t
• Parallel I/O
  • Class File: the Parallel I/O Handler
• Other Standard Facilities
  • Class Message: Probing and Matching
  • Class Info: the Hints to MPI Implementation
  • Memory Management
  • Timer

MPI Extensions

• Synchronizations
  • SpinLock and Mutex
  • Lock Guards
  • Sequential Block
• Master-slave Models
• Symmetric Models
• Work Decomposition

Intermediate-level API

• Intermediate-level API Overview

References

MPIForum-STDv31

Message Passing Interface Forum, MPI: A Message Passing Interface Standard (version 3.1).

GroppW-UMPIv3

William Gropp, Ewing Lusk, and Anthony Skjellum, Using MPI - Portable Parallel Programming with the Message-Passing Interface (3ed).

GroppW-UAMPI

William Gropp, Torsten Hoefler, Rajeev Thakur, Ewing Lusk, Using Advanced MPI - Modern Features of the Message-Passing Interface.

DuZH-MPIv2001

Zhihui Du, 高性能计算之并行编程技术 - MPI并行程序设计 (2001年版).