Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

PrevUpHomeNext

Mapping from C MPI to Boost.MPI

This section provides tables that map from the functions and constants of the standard C MPI to their Boost.MPI equivalents. It will be most useful for users that are already familiar with the C or Fortran interfaces to MPI, or for porting existing parallel programs to Boost.MPI.

Note that this is not a perfect one to one mapping, the Boost.MPI will sometime use function from the C API in a way that is transparent for the end user. For example, MPI_Probe and friends can be used to implement asynchronous send/recv.

Table 24.1. Point-to-point communication


Boost.MPI automatically maps C and C++ data types to their MPI equivalents. The following table illustrates the mappings between C++ types and MPI datatype constants.

Table 24.2. Datatypes

C Constant

Boost.MPI Equivalent

MPI_CHAR

signed char

MPI_SHORT

signed short int

MPI_INT

signed int

MPI_LONG

signed long int

MPI_UNSIGNED_CHAR

unsigned char

MPI_UNSIGNED_SHORT

unsigned short int

MPI_UNSIGNED_INT

unsigned int

MPI_UNSIGNED_LONG

unsigned long int

MPI_FLOAT

float

MPI_DOUBLE

double

MPI_LONG_DOUBLE

long double

MPI_BYTE

unused

MPI_PACKED

used internally for serialized data types

MPI_LONG_LONG_INT

long long int, if supported by compiler

MPI_UNSIGNED_LONG_LONG_INT

unsigned long long int, if supported by compiler

MPI_FLOAT_INT

std::pair<float, int>

MPI_DOUBLE_INT

std::pair<double, int>

MPI_LONG_INT

std::pair<long, int>

MPI_2INT

std::pair<int, int>

MPI_SHORT_INT

std::pair<short, int>

MPI_LONG_DOUBLE_INT

std::pair<long double, int>


Boost.MPI does not provide direct wrappers to the MPI derived datatypes functionality. Instead, Boost.MPI relies on the Boost.Serialization library to construct MPI datatypes for user-defined classes. The section on user-defined data types describes this mechanism, which is used for types that marked as "MPI datatypes" using is_mpi_datatype.

The derived datatypes table that follows describes which C++ types correspond to the functionality of the C MPI's datatype constructor. Boost.MPI may not actually use the C MPI function listed when building datatypes of a certain form. Since the actual datatypes built by Boost.MPI are typically hidden from the user, many of these operations are called internally by Boost.MPI.

Table 24.3. Derived datatypes

C Function/Constant

Boost.MPI Equivalent

MPI_Address

used automatically in Boost.MPI for MPI version 1.x

MPI_Get_address

used automatically in Boost.MPI for MPI version 2.0 and higher

MPI_Type_commit

used automatically in Boost.MPI

MPI_Type_contiguous

arrays

MPI_Type_extent

used automatically in Boost.MPI

MPI_Type_free

used automatically in Boost.MPI

MPI_Type_hindexed

any type used as a subobject

MPI_Type_hvector

unused

MPI_Type_indexed

any type used as a subobject

MPI_Type_lb

unsupported

MPI_Type_size

used automatically in Boost.MPI

MPI_Type_struct

user-defined classes and structs with MPI 1.x

MPI_Type_create_struct

user-defined classes and structs with MPI 2.0 and higher

MPI_Type_ub

unsupported

MPI_Type_vector

used automatically in Boost.MPI


MPI's packing facilities store values into a contiguous buffer, which can later be transmitted via MPI and unpacked into separate values via MPI's unpacking facilities. As with datatypes, Boost.MPI provides an abstract interface to MPI's packing and unpacking facilities. In particular, the two archive classes packed_oarchive and packed_iarchive can be used to pack or unpack a contiguous buffer using MPI's facilities.

Table 24.4. Packing and unpacking

C Function

Boost.MPI Equivalent

MPI_Pack

packed_oarchive

MPI_Pack_size

used internally by Boost.MPI

MPI_Unpack

packed_iarchive


Boost.MPI supports a one-to-one mapping for most of the MPI collectives. For each collective provided by Boost.MPI, the underlying C MPI collective will be invoked when it is possible (and efficient) to do so.

Table 24.5. Collectives

C Function

Boost.MPI Equivalent

MPI_Allgather

all_gather

MPI_Allgatherv

most uses supported by all_gather

MPI_Allreduce

all_reduce

MPI_Alltoall

all_to_all

MPI_Alltoallv

most uses supported by all_to_all

MPI_Barrier

communicator::barrier

MPI_Bcast

broadcast

MPI_Gather

gather

MPI_Gatherv

most uses supported by gather, other usages supported by gatherv

MPI_Reduce

reduce

MPI_Reduce_scatter

unsupported

MPI_Scan

scan

MPI_Scatter

scatter

MPI_Scatterv

most uses supported by scatter, other uses supported by scatterv

MPI_IN_PLACE

supported implicitly by all_reduce by omitting the output value


Boost.MPI uses function objects to specify how reductions should occur in its equivalents to MPI_Allreduce, MPI_Reduce, and MPI_Scan. The following table illustrates how predefined and user-defined reduction operations can be mapped between the C MPI and Boost.MPI.

Table 24.6. Reduction operations

C Constant

Boost.MPI Equivalent

MPI_BAND

bitwise_and

MPI_BOR

bitwise_or

MPI_BXOR

bitwise_xor

MPI_LAND

std::logical_and

MPI_LOR

std::logical_or

MPI_LXOR

logical_xor

MPI_MAX

maximum

MPI_MAXLOC

unsupported

MPI_MIN

minimum

MPI_MINLOC

unsupported

MPI_Op_create

used internally by Boost.MPI

MPI_Op_free

used internally by Boost.MPI

MPI_PROD

std::multiplies

MPI_SUM

std::plus


MPI defines several special communicators, including MPI_COMM_WORLD (including all processes that the local process can communicate with), MPI_COMM_SELF (including only the local process), and MPI_COMM_EMPTY (including no processes). These special communicators are all instances of the communicator class in Boost.MPI.

Table 24.7. Predefined communicators

C Constant

Boost.MPI Equivalent

MPI_COMM_WORLD

a default-constructed communicator

MPI_COMM_SELF

a communicator that contains only the current process

MPI_COMM_EMPTY

a communicator that evaluates false


Boost.MPI supports groups of processes through its group class.

Table 24.8. Group operations and constants

C Function/Constant

Boost.MPI Equivalent

MPI_GROUP_EMPTY

a default-constructed group

MPI_Group_size

group::size

MPI_Group_rank

memberref boost::mpi::group::rank group::rank

MPI_Group_translate_ranks

memberref boost::mpi::group::translate_ranks group::translate_ranks

MPI_Group_compare

operators == and !=

MPI_IDENT

operators == and !=

MPI_SIMILAR

operators == and !=

MPI_UNEQUAL

operators == and !=

MPI_Comm_group

communicator::group

MPI_Group_union

operator | for groups

MPI_Group_intersection

operator & for groups

MPI_Group_difference

operator - for groups

MPI_Group_incl

group::include

MPI_Group_excl

group::exclude

MPI_Group_range_incl

unsupported

MPI_Group_range_excl

unsupported

MPI_Group_free

used automatically in Boost.MPI


Boost.MPI provides manipulation of communicators through the communicator class.

Table 24.9. Communicator operations

C Function

Boost.MPI Equivalent

MPI_Comm_size

communicator::size

MPI_Comm_rank

communicator::rank

MPI_Comm_compare

operators == and !=

MPI_Comm_dup

communicator class constructor using comm_duplicate

MPI_Comm_create

communicator constructor

MPI_Comm_split

communicator::split

MPI_Comm_free

used automatically in Boost.MPI


Boost.MPI currently provides support for inter-communicators via the intercommunicator class.

Table 24.10. Inter-communicator operations


Boost.MPI currently provides no support for attribute caching.

Table 24.11. Attributes and caching

C Function/Constant

Boost.MPI Equivalent

MPI_NULL_COPY_FN

unsupported

MPI_NULL_DELETE_FN

unsupported

MPI_KEYVAL_INVALID

unsupported

MPI_Keyval_create

unsupported

MPI_Copy_function

unsupported

MPI_Delete_function

unsupported

MPI_Keyval_free

unsupported

MPI_Attr_put

unsupported

MPI_Attr_get

unsupported

MPI_Attr_delete

unsupported


Boost.MPI will provide complete support for creating communicators with different topologies and later querying those topologies. Support for graph topologies is provided via an interface to the Boost Graph Library (BGL), where a communicator can be created which matches the structure of any BGL graph, and the graph topology of a communicator can be viewed as a BGL graph for use in existing, generic graph algorithms.

Table 24.12. Process topologies


Boost.MPI supports environmental inquires through the environment class.

Table 24.13. Environmental inquiries

C Function/Constant

Boost.MPI Equivalent

MPI_TAG_UB

unnecessary; use environment::max_tag

MPI_HOST

unnecessary; use environment::host_rank

MPI_IO

unnecessary; use environment::io_rank

MPI_Get_processor_name

environment::processor_name


Boost.MPI translates MPI errors into exceptions, reported via the exception class.

Table 24.14. Error handling

C Function/Constant

Boost.MPI Equivalent

MPI_ERRORS_ARE_FATAL

unused; errors are translated into Boost.MPI exceptions

MPI_ERRORS_RETURN

unused; errors are translated into Boost.MPI exceptions

MPI_errhandler_create

unused; errors are translated into Boost.MPI exceptions

MPI_errhandler_set

unused; errors are translated into Boost.MPI exceptions

MPI_errhandler_get

unused; errors are translated into Boost.MPI exceptions

MPI_errhandler_free

unused; errors are translated into Boost.MPI exceptions

MPI_Error_string

used internally by Boost.MPI

MPI_Error_class

exception::error_class


The MPI timing facilities are exposed via the Boost.MPI timer class, which provides an interface compatible with the Boost Timer library.

Table 24.15. Timing facilities

C Function/Constant

Boost.MPI Equivalent

MPI_WTIME_IS_GLOBAL

unnecessary; use timer::time_is_global

MPI_Wtime

use timer::elapsed to determine the time elapsed from some specific starting point

MPI_Wtick

timer::elapsed_min


MPI startup and shutdown are managed by the construction and destruction of the Boost.MPI environment class.

Table 24.16. Startup/shutdown facilities


Boost.MPI does not provide any support for the profiling facilities in MPI 1.1.

Table 24.17. Profiling interface

C Function

Boost.MPI Equivalent

PMPI_* routines

unsupported

MPI_Pcontrol

unsupported



PrevUpHomeNext