mpi.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

      broadcast(world, c, 0);

      if (std::find_if
           (l.begin(), l.end(),
            std::bind1st(std::not_equal_to<int>(), 0)) == l.end())
        break;

      // Compute some property of the data.

      ++i;
    } while (true);


The skeletons and content of any Serializable data type can be
transmitted either via the [memberref
boost::mpi::communicator::send `send`] and [memberref
boost::mpi::communicator::recv `recv`] members of the
[classref boost::mpi::communicator `communicator`] class
(for point-to-point communicators) or broadcast via the [funcref
boost::mpi::broadcast `broadcast()`] collective. When
separating a data structure into a skeleton and content, be careful
not to modify the data structure (either on the sender side or the
receiver side) without transmitting the skeleton again. Boost.MPI can
not detect these accidental modifications to the data structure, which
will likely result in incorrect data being transmitted or unstable
programs. 

[endsect]




[section:performance_optimizations Performance optimizations]
[section:serialization_optimizations Serialization optimizations]

To obtain optimal performance for small fixed-length data types not containing
any pointers it is very important to mark them using the type traits of
Boost.MPI and Boost.Serialization. 

It was alredy discussed that fixed length types containing no pointers can be 
using as [classref
boost::mpi::is_mpi_datatype `is_mpi_datatype`], e.g.:

  namespace boost { namespace mpi {
    template <>
    struct is_mpi_datatype<gps_position> : mpl::true_ { };
  } }

or the equivalent macro 

  BOOST_IS_MPI_DATATYPE(gps_position)
  
In addition it can give a substantial performance gain to turn off tracking
and versioning for these types, if no pointers to these types are used, by
using the traits classes or helper macros of Boost.Serialization:

  BOOST_CLASS_TRACKING(gps_position,track_never)
  BOOST_CLASS_IMPLEMENTATION(gps_position,object_serializable)

[endsect]
  
[section:homogeneous_machines Homogeneous machines]

More optimizations are possible on homogeneous machines, by avoiding
MPI_Pack/MPI_Unpack calls but using direct bitwise copy. This feature can be
enabled by defining the macro BOOST_MPI_HOMOGENEOUS when building Boost.MPI and
when building the application.

In addition all classes need to be marked both as is_mpi_datatype and
as is_bitwise_serializable, by using the helper macro of Boost.Serialization:

  BOOST_IS_BITWISE_SERIALIZABLE(gps_position)

Usually it is safe to serialize a class for which is_mpi_datatype is true 
by using binary copy of the bits. The exception are classes for which
some members should be skipped for serialization.

[endsect]
[endsect]


[section:c_mapping 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.

[table Point-to-point communication
  [[C Function/Constant] [Boost.MPI Equivalent]]

  [[`MPI_ANY_SOURCE`] [`any_source`]]

  [[`MPI_ANY_TAG`] [`any_tag`]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40
`MPI_Bsend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Bsend_init`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node42.html#Node42
`MPI_Buffer_attach`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node42.html#Node42
`MPI_Buffer_detach`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50
`MPI_Cancel`]] 
   [[memberref boost::mpi::request::cancel
`request::cancel`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node35.html#Node35
`MPI_Get_count`]] 
   [[memberref boost::mpi::status::count `status::count`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46
`MPI_Ibsend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50
`MPI_Iprobe`]]
   [[memberref boost::mpi::communicator::iprobe `communicator::iprobe`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46
`MPI_Irsend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46
`MPI_Isend`]] 
   [[memberref boost::mpi::communicator::isend
`communicator::isend`]]] 

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46
`MPI_Issend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node46.html#Node46
`MPI_Irecv`]] 
   [[memberref boost::mpi::communicator::isend
`communicator::irecv`]]] 

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50
`MPI_Probe`]]
   [[memberref boost::mpi::communicator::probe `communicator::probe`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node53.html#Node53
`MPI_PROC_NULL`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node34.html#Node34 `MPI_Recv`]]
   [[memberref boost::mpi::communicator::recv
`communicator::recv`]]] 

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Recv_init`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Request_free`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40
`MPI_Rsend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Rsend_init`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node31.html#Node31
`MPI_Send`]]
   [[memberref boost::mpi::communicator::send
`communicator::send`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node52.html#Node52
`MPI_Sendrecv`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node52.html#Node52
`MPI_Sendrecv_replace`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Send_init`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node40.html#Node40
`MPI_Ssend`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Ssend_init`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Start`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node51.html#Node51
`MPI_Startall`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Test`]] [[memberref boost::mpi::request::wait `request::test`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Testall`]] [[funcref boost::mpi::test_all `test_all`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Testany`]] [[funcref boost::mpi::test_any `test_any`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Testsome`]] [[funcref boost::mpi::test_some `test_some`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node50.html#Node50
`MPI_Test_cancelled`]] 
   [[memberref boost::mpi::status::cancelled
`status::cancelled`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Wait`]] [[memberref boost::mpi::request::wait
`request::wait`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Waitall`]] [[funcref boost::mpi::wait_all `wait_all`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Waitany`]] [[funcref boost::mpi::wait_any `wait_any`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node47.html#Node47
`MPI_Waitsome`]] [[funcref boost::mpi::wait_some `wait_some`]]]
]

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 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 [link
mpi.user_data_types 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
_Serialization_ library to construct MPI datatypes for user-defined
classe. The section on [link mpi.user_data_types user-defined
data types] describes this mechanism, which is used for types that
marked as "MPI datatypes" using [classref
boost::mpi::is_mpi_datatype `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 Derived datatypes
  [[C Function/Constant] [Boost.MPI Equivalent]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56
`MPI_Address`]] [used automatically in Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node58.html#Node58
`MPI_Type_commit`]] [used automatically in Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`MPI_Type_contiguous`]] [arrays]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56
`MPI_Type_extent`]] [used automatically in Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node58.html#Node58
`MPI_Type_free`]] [used automatically in Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`MPI_Type_hindexed`]] [any type used as a subobject]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`MPI_Type_hvector`]] [unused]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`MPI_Type_indexed`]] [any type used as a subobject]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node57.html#Node57
`MPI_Type_lb`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node56.html#Node56
`MPI_Type_size`]] [used automatically in Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`MPI_Type_struct`]] [user-defined classes and structs]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node57.html#Node57
`MPI_Type_ub`]] [unsupported]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node55.html#Node55
`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 [classref
boost::mpi::packed_oarchive `packed_oarchive`] and [classref
boost::mpi::packed_iarchive `packed_iarchive`] can be used
to pack or unpack a contiguous buffer using MPI's facilities.

[table Packing and unpacking
  [[C Function] [Boost.MPI Equivalent]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62
`MPI_Pack`]] [[classref
boost::mpi::packed_oarchive `packed_oarchive`]]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62
`MPI_Pack_size`]] [used internally by Boost.MPI]]

  [[[@http://www.mpi-forum.org/docs/mpi-11-html/node62.html#Node62
`MPI_Unpack`]] [[classref