libs/mpi/doc/c_mapping.qbk

   1 [section:c_mapping Mapping from C MPI to Boost.MPI]
   2
   3 This section provides tables that map from the functions and constants
   4 of the standard C MPI to their Boost.MPI equivalents. It will be most
   5 useful for users that are already familiar with the C or Fortran
   6 interfaces to MPI, or for porting existing parallel programs to Boost.MPI.
   7
   8 Note that this is not a perfect one to one mapping, the Boost.MPI will sometime
   9 use function from the C API in a way that is transparent for the end user.
  10 For example, [@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node50.html#Node50
  11 `MPI_Probe and friends`] can be used to implement asynchronous send/recv.
  12
  13 [table Point-to-point communication
  14   [[C Function/Constant] [Boost.MPI Equivalent]]
  15
  16   [[`MPI_ANY_SOURCE`] [`any_source`]]
  17
  18   [[`MPI_ANY_TAG`] [`any_tag`]]
  19
  20   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node40.html#Node40
  21 `MPI_Bsend`]] [unsupported]]
  22
  23   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
  24 `MPI_Bsend_init`]] [unsupported]]
  25
  26   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node42.html#Node42
  27 `MPI_Buffer_attach`]] [unsupported]]
  28
  29   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node42.html#Node42
  30 `MPI_Buffer_detach`]] [unsupported]]
  31
  32   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node50.html#Node50
  33 `MPI_Cancel`]]
  34    [[memberref boost::mpi::request::cancel
  35 `request::cancel`]]]
  36
  37   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node35.html#Node35
  38 `MPI_Get_count`]]
  39    [[memberref boost::mpi::status::count `status::count`]]]
  40
  41   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node46.html#Node46
  42 `MPI_Ibsend`]] [unsupported]]
  43
  44   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node50.html#Node50
  45 `MPI_Iprobe`]]
  46    [[memberref boost::mpi::communicator::iprobe `communicator::iprobe`]]]
  47
  48   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node46.html#Node46
  49 `MPI_Irsend`]] [unsupported]]
  50
  51   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node46.html#Node46
  52 `MPI_Isend`]]
  53    [[memberref boost::mpi::communicator::isend
  54 `communicator::isend`]]]
  55
  56   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node46.html#Node46
  57 `MPI_Issend`]] [unsupported]]
  58
  59   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node46.html#Node46
  60 `MPI_Irecv`]]
  61    [[memberref boost::mpi::communicator::isend
  62 `communicator::irecv`]]]
  63
  64   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node50.html#Node50
  65 `MPI_Probe`]]
  66    [[memberref boost::mpi::communicator::probe `communicator::probe`]]]
  67
  68   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node53.html#Node53
  69 `MPI_PROC_NULL`]] [unsupported]]
  70
  71   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node34.html#Node34 `MPI_Recv`]]
  72    [[memberref boost::mpi::communicator::recv
  73 `communicator::recv`]]]
  74
  75   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
  76 `MPI_Recv_init`]] [unsupported]]
  77
  78   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
  79 `MPI_Request_free`]] [unsupported]]
  80
  81   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node40.html#Node40
  82 `MPI_Rsend`]] [unsupported]]
  83
  84   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
  85 `MPI_Rsend_init`]] [unsupported]]
  86
  87   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node31.html#Node31
  88 `MPI_Send`]]
  89    [[memberref boost::mpi::communicator::send
  90 `communicator::send`]]]
  91
  92   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node52.html#Node52
  93 `MPI_Sendrecv`]] [[memberref boost::mpi::communicator::sendrecv
  94 `communicator::sendrecv`]]]
  95
  96   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node52.html#Node52
  97 `MPI_Sendrecv_replace`]] [unsupported]]
  98
  99   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
 100 `MPI_Send_init`]] [unsupported]]
 101
 102   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node40.html#Node40
 103 `MPI_Ssend`]] [unsupported]]
 104
 105   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
 106 `MPI_Ssend_init`]] [unsupported]]
 107
 108   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
 109 `MPI_Start`]] [unsupported]]
 110
 111   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node51.html#Node51
 112 `MPI_Startall`]] [unsupported]]
 113
 114   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 115 `MPI_Test`]] [[memberref boost::mpi::request::wait `request::test`]]]
 116
 117   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 118 `MPI_Testall`]] [[funcref boost::mpi::test_all `test_all`]]]
 119
 120   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 121 `MPI_Testany`]] [[funcref boost::mpi::test_any `test_any`]]]
 122
 123   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 124 `MPI_Testsome`]] [[funcref boost::mpi::test_some `test_some`]]]
 125
 126   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node50.html#Node50
 127 `MPI_Test_cancelled`]]
 128    [[memberref boost::mpi::status::cancelled
 129 `status::cancelled`]]]
 130
 131   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 132 `MPI_Wait`]] [[memberref boost::mpi::request::wait
 133 `request::wait`]]]
 134
 135   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 136 `MPI_Waitall`]] [[funcref boost::mpi::wait_all `wait_all`]]]
 137
 138   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 139 `MPI_Waitany`]] [[funcref boost::mpi::wait_any `wait_any`]]]
 140
 141   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node47.html#Node47
 142 `MPI_Waitsome`]] [[funcref boost::mpi::wait_some `wait_some`]]]
 143 ]
 144
 145 Boost.MPI automatically maps C and C++ data types to their MPI
 146 equivalents. The following table illustrates the mappings between C++
 147 types and MPI datatype constants.
 148
 149 [table Datatypes
 150   [[C Constant] [Boost.MPI Equivalent]]
 151
 152   [[`MPI_CHAR`] [`signed char`]]
 153   [[`MPI_SHORT`] [`signed short int`]]
 154   [[`MPI_INT`] [`signed int`]]
 155   [[`MPI_LONG`] [`signed long int`]]
 156   [[`MPI_UNSIGNED_CHAR`] [`unsigned char`]]
 157   [[`MPI_UNSIGNED_SHORT`] [`unsigned short int`]]
 158   [[`MPI_UNSIGNED_INT`] [`unsigned int`]]
 159   [[`MPI_UNSIGNED_LONG`] [`unsigned long int`]]
 160   [[`MPI_FLOAT`] [`float`]]
 161   [[`MPI_DOUBLE`] [`double`]]
 162   [[`MPI_LONG_DOUBLE`] [`long double`]]
 163   [[`MPI_BYTE`] [unused]]
 164   [[`MPI_PACKED`] [used internally for [link
 165 mpi.tutorial.user_data_types serialized data types]]]
 166   [[`MPI_LONG_LONG_INT`] [`long long int`, if supported by compiler]]
 167   [[`MPI_UNSIGNED_LONG_LONG_INT`] [`unsigned long long int`, if
 168 supported by compiler]]
 169   [[`MPI_FLOAT_INT`] [`std::pair<float, int>`]]
 170   [[`MPI_DOUBLE_INT`] [`std::pair<double, int>`]]
 171   [[`MPI_LONG_INT`] [`std::pair<long, int>`]]
 172   [[`MPI_2INT`] [`std::pair<int, int>`]]
 173   [[`MPI_SHORT_INT`] [`std::pair<short, int>`]]
 174   [[`MPI_LONG_DOUBLE_INT`] [`std::pair<long double, int>`]]
 175 ]
 176
 177 Boost.MPI does not provide direct wrappers to the MPI derived
 178 datatypes functionality. Instead, Boost.MPI relies on the
 179 _Serialization_ library to construct MPI datatypes for user-defined
 180 classes. The section on [link mpi.tutorial.user_data_types user-defined
 181 data types] describes this mechanism, which is used for types that
 182 marked as "MPI datatypes" using [classref
 183 boost::mpi::is_mpi_datatype `is_mpi_datatype`].
 184
 185 The derived datatypes table that follows describes which C++ types
 186 correspond to the functionality of the C MPI's datatype
 187 constructor. Boost.MPI may not actually use the C MPI function listed
 188 when building datatypes of a certain form. Since the actual datatypes
 189 built by Boost.MPI are typically hidden from the user, many of these
 190 operations are called internally by Boost.MPI.
 191
 192 [table Derived datatypes
 193   [[C Function/Constant] [Boost.MPI Equivalent]]
 194
 195   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node56.html#Node56
 196 `MPI_Address`]] [used automatically in Boost.MPI for MPI version 1.x]]
 197
 198   [[[@http://www.mpi-forum.org/docs/mpi-20-html/node76.htm#Node76
 199 `MPI_Get_address`]] [used automatically in Boost.MPI for MPI version 2.0 and higher]]
 200
 201   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node58.html#Node58
 202 `MPI_Type_commit`]] [used automatically in Boost.MPI]]
 203
 204   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 205 `MPI_Type_contiguous`]] [arrays]]
 206
 207   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node56.html#Node56
 208 `MPI_Type_extent`]] [used automatically in Boost.MPI]]
 209
 210   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node58.html#Node58
 211 `MPI_Type_free`]] [used automatically in Boost.MPI]]
 212
 213   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 214 `MPI_Type_hindexed`]] [any type used as a subobject]]
 215
 216   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 217 `MPI_Type_hvector`]] [unused]]
 218
 219   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 220 `MPI_Type_indexed`]] [any type used as a subobject]]
 221
 222   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node57.html#Node57
 223 `MPI_Type_lb`]] [unsupported]]
 224
 225   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node56.html#Node56
 226 `MPI_Type_size`]] [used automatically in Boost.MPI]]
 227
 228   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 229 `MPI_Type_struct`]] [user-defined classes and structs with MPI 1.x]]
 230
 231   [[[@http://www.mpi-forum.org/docs/mpi-20-html/node76.htm#Node76
 232 `MPI_Type_create_struct`]] [user-defined classes and structs with MPI 2.0 and higher]]
 233
 234   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node57.html#Node57
 235 `MPI_Type_ub`]] [unsupported]]
 236
 237   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node55.html#Node55
 238 `MPI_Type_vector`]] [used automatically in Boost.MPI]]
 239 ]
 240
 241 MPI's packing facilities store values into a contiguous buffer, which
 242 can later be transmitted via MPI and unpacked into separate values via
 243 MPI's unpacking facilities. As with datatypes, Boost.MPI provides an
 244 abstract interface to MPI's packing and unpacking facilities. In
 245 particular, the two archive classes [classref
 246 boost::mpi::packed_oarchive `packed_oarchive`] and [classref
 247 boost::mpi::packed_iarchive `packed_iarchive`] can be used
 248 to pack or unpack a contiguous buffer using MPI's facilities.
 249
 250 [table Packing and unpacking
 251   [[C Function] [Boost.MPI Equivalent]]
 252
 253   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node62.html#Node62
 254 `MPI_Pack`]] [[classref
 255 boost::mpi::packed_oarchive `packed_oarchive`]]]
 256
 257   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node62.html#Node62
 258 `MPI_Pack_size`]] [used internally by Boost.MPI]]
 259
 260   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node62.html#Node62
 261 `MPI_Unpack`]] [[classref
 262 boost::mpi::packed_iarchive `packed_iarchive`]]]
 263 ]
 264
 265 Boost.MPI supports a one-to-one mapping for most of the MPI
 266 collectives. For each collective provided by Boost.MPI, the underlying
 267 C MPI collective will be invoked when it is possible (and efficient)
 268 to do so.
 269
 270 [table Collectives
 271   [[C Function] [Boost.MPI Equivalent]]
 272
 273   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node73.html#Node73
 274 `MPI_Allgather`]] [[funcref boost::mpi::all_gather `all_gather`]]]
 275
 276   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node73.html#Node73
 277 `MPI_Allgatherv`]] [most uses supported by [funcref boost::mpi::all_gather `all_gather`]]]
 278
 279   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node82.html#Node82
 280 `MPI_Allreduce`]] [[funcref boost::mpi::all_reduce `all_reduce`]]]
 281
 282   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node75.html#Node75
 283 `MPI_Alltoall`]] [[funcref boost::mpi::all_to_all `all_to_all`]]]
 284
 285   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node75.html#Node75
 286 `MPI_Alltoallv`]] [most uses supported by [funcref boost::mpi::all_to_all `all_to_all`]]]
 287
 288   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node66.html#Node66
 289 `MPI_Barrier`]] [[memberref
 290 boost::mpi::communicator::barrier `communicator::barrier`]]]
 291
 292   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node67.html#Node67
 293 `MPI_Bcast`]] [[funcref boost::mpi::broadcast `broadcast`]]]
 294
 295   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node69.html#Node69
 296 `MPI_Gather`]] [[funcref boost::mpi::gather `gather`]]]
 297
 298   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node69.html#Node69
 299 `MPI_Gatherv`]] [most uses supported by [funcref boost::mpi::gather `gather`],
 300 other usages supported by [funcref boost::mpi::gatherv `gatherv`]]]
 301
 302   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node77.html#Node77
 303 `MPI_Reduce`]] [[funcref boost::mpi::reduce `reduce`]]]
 304
 305   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node83.html#Node83
 306 `MPI_Reduce_scatter`]] [unsupported]]
 307
 308   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node84.html#Node84
 309 `MPI_Scan`]] [[funcref boost::mpi::scan `scan`]]]
 310
 311   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node71.html#Node71
 312 `MPI_Scatter`]] [[funcref boost::mpi::scatter `scatter`]]]
 313
 314   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node71.html#Node71
 315 `MPI_Scatterv`]] [most uses supported by [funcref boost::mpi::scatter `scatter`],
 316 other uses supported by [funcref boost::mpi::scatterv `scatterv`]]]
 317
 318   [[[@http://www.mpi-forum.org/docs/mpi-20-html/node145.htm#Node145
 319 `MPI_IN_PLACE`]] [supported implicitly by [funcref boost::mpi::all_reduce
 320 `all_reduce` by omitting the output value]]]
 321 ]
 322
 323 Boost.MPI uses function objects to specify how reductions should occur
 324 in its equivalents to `MPI_Allreduce`, `MPI_Reduce`, and
 325 `MPI_Scan`. The following table illustrates how
 326 [@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node78.html#Node78
 327 predefined] and
 328 [@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node80.html#Node80
 329 user-defined] reduction operations can be mapped between the C MPI and
 330 Boost.MPI.
 331
 332 [table Reduction operations
 333   [[C Constant] [Boost.MPI Equivalent]]
 334
 335   [[`MPI_BAND`] [[classref boost::mpi::bitwise_and `bitwise_and`]]]
 336   [[`MPI_BOR`] [[classref boost::mpi::bitwise_or `bitwise_or`]]]
 337   [[`MPI_BXOR`] [[classref boost::mpi::bitwise_xor `bitwise_xor`]]]
 338   [[`MPI_LAND`] [`std::logical_and`]]
 339   [[`MPI_LOR`] [`std::logical_or`]]
 340   [[`MPI_LXOR`] [[classref boost::mpi::logical_xor `logical_xor`]]]
 341   [[`MPI_MAX`] [[classref boost::mpi::maximum `maximum`]]]
 342   [[`MPI_MAXLOC`] [unsupported]]
 343   [[`MPI_MIN`] [[classref boost::mpi::minimum `minimum`]]]
 344   [[`MPI_MINLOC`] [unsupported]]
 345   [[`MPI_Op_create`] [used internally by Boost.MPI]]
 346   [[`MPI_Op_free`] [used internally by Boost.MPI]]
 347   [[`MPI_PROD`] [`std::multiplies`]]
 348   [[`MPI_SUM`] [`std::plus`]]
 349 ]
 350
 351 MPI defines several special communicators, including `MPI_COMM_WORLD`
 352 (including all processes that the local process can communicate with),
 353 `MPI_COMM_SELF` (including only the local process), and
 354 `MPI_COMM_EMPTY` (including no processes). These special communicators
 355 are all instances of the [classref boost::mpi::communicator
 356 `communicator`] class in Boost.MPI.
 357
 358 [table Predefined communicators
 359   [[C Constant] [Boost.MPI Equivalent]]
 360
 361   [[`MPI_COMM_WORLD`] [a default-constructed [classref boost::mpi::communicator `communicator`]]]
 362   [[`MPI_COMM_SELF`] [a [classref boost::mpi::communicator `communicator`] that contains only the current process]]
 363   [[`MPI_COMM_EMPTY`] [a [classref boost::mpi::communicator `communicator`] that evaluates false]]
 364 ]
 365
 366 Boost.MPI supports groups of processes through its [classref
 367 boost::mpi::group `group`] class.
 368
 369 [table Group operations and constants
 370   [[C Function/Constant] [Boost.MPI Equivalent]]
 371
 372   [[`MPI_GROUP_EMPTY`] [a default-constructed [classref
 373   boost::mpi::group `group`]]]
 374   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node97.html#Node97
 375   `MPI_Group_size`]] [[memberref boost::mpi::group::size `group::size`]]]
 376   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node97.html#Node97
 377   `MPI_Group_rank`]] [memberref boost::mpi::group::rank `group::rank`]]
 378   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node97.html#Node97
 379   `MPI_Group_translate_ranks`]] [memberref boost::mpi::group::translate_ranks `group::translate_ranks`]]
 380   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node97.html#Node97
 381   `MPI_Group_compare`]] [operators `==` and `!=`]]
 382   [[`MPI_IDENT`] [operators `==` and `!=`]]
 383   [[`MPI_SIMILAR`] [operators `==` and `!=`]]
 384   [[`MPI_UNEQUAL`] [operators `==` and `!=`]]
 385   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 386   `MPI_Comm_group`]] [[memberref
 387   boost::mpi::communicator::group `communicator::group`]]]
 388   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 389   `MPI_Group_union`]] [operator `|` for groups]]
 390   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 391   `MPI_Group_intersection`]] [operator `&` for groups]]
 392   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 393   `MPI_Group_difference`]] [operator `-` for groups]]
 394   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 395   `MPI_Group_incl`]] [[memberref boost::mpi::group::include `group::include`]]]
 396   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 397   `MPI_Group_excl`]] [[memberref boost::mpi::group::include `group::exclude`]]]
 398   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 399   `MPI_Group_range_incl`]] [unsupported]]
 400   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node98.html#Node98
 401   `MPI_Group_range_excl`]] [unsupported]]
 402   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node99.html#Node99
 403   `MPI_Group_free`]] [used automatically in Boost.MPI]]
 404 ]
 405
 406 Boost.MPI provides manipulation of communicators through the [classref
 407 boost::mpi::communicator `communicator`] class.
 408
 409 [table Communicator operations
 410   [[C Function] [Boost.MPI Equivalent]]
 411
 412   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node101.html#Node101
 413   `MPI_Comm_size`]] [[memberref boost::mpi::communicator::size `communicator::size`]]]
 414   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node101.html#Node101
 415   `MPI_Comm_rank`]] [[memberref boost::mpi::communicator::rank
 416   `communicator::rank`]]]
 417   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node101.html#Node101
 418   `MPI_Comm_compare`]] [operators `==` and `!=`]]
 419   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node102.html#Node102
 420   `MPI_Comm_dup`]] [[classref boost::mpi::communicator `communicator`]
 421   class constructor using `comm_duplicate`]]
 422   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node102.html#Node102
 423   `MPI_Comm_create`]] [[classref boost::mpi::communicator
 424   `communicator`] constructor]]
 425   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node102.html#Node102
 426   `MPI_Comm_split`]] [[memberref boost::mpi::communicator::split
 427   `communicator::split`]]]
 428   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node103.html#Node103
 429   `MPI_Comm_free`]] [used automatically in Boost.MPI]]
 430 ]
 431
 432 Boost.MPI currently provides support for inter-communicators via the
 433 [classref boost::mpi::intercommunicator `intercommunicator`] class.
 434
 435 [table Inter-communicator operations
 436   [[C Function] [Boost.MPI Equivalent]]
 437
 438   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node112.html#Node112
 439   `MPI_Comm_test_inter`]] [use [memberref boost::mpi::communicator::as_intercommunicator `communicator::as_intercommunicator`]]]
 440   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node112.html#Node112
 441   `MPI_Comm_remote_size`]] [[memberref boost::mpi::intercommunicator::remote_size] `intercommunicator::remote_size`]]
 442   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node112.html#Node112
 443   `MPI_Comm_remote_group`]] [[memberref boost::mpi::intercommunicator::remote_group `intercommunicator::remote_group`]]]
 444   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node113.html#Node113
 445   `MPI_Intercomm_create`]] [[classref boost::mpi::intercommunicator `intercommunicator`] constructor]]
 446   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node113.html#Node113
 447   `MPI_Intercomm_merge`]] [[memberref boost::mpi::intercommunicator::merge `intercommunicator::merge`]]]
 448 ]
 449
 450 Boost.MPI currently provides no support for attribute caching.
 451
 452 [table Attributes and caching
 453  [[C Function/Constant] [Boost.MPI Equivalent]]
 454
 455  [[`MPI_NULL_COPY_FN`] [unsupported]]
 456  [[`MPI_NULL_DELETE_FN`] [unsupported]]
 457  [[`MPI_KEYVAL_INVALID`] [unsupported]]
 458  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 459  `MPI_Keyval_create`]] [unsupported]]
 460  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 461  `MPI_Copy_function`]] [unsupported]]
 462  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 463  `MPI_Delete_function`]] [unsupported]]
 464  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 465  `MPI_Keyval_free`]] [unsupported]]
 466  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 467  `MPI_Attr_put`]] [unsupported]]
 468  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 469  `MPI_Attr_get`]] [unsupported]]
 470  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node119.html#Node119
 471  `MPI_Attr_delete`]] [unsupported]]
 472 ]
 473
 474 Boost.MPI will provide complete support for creating communicators
 475 with different topologies and later querying those topologies. Support
 476 for graph topologies is provided via an interface to the
 477 [@http://www.boost.org/libs/graph/doc/index.html Boost Graph Library
 478 (BGL)], where a communicator can be created which matches the
 479 structure of any BGL graph, and the graph topology of a communicator
 480 can be viewed as a BGL graph for use in existing, generic graph
 481 algorithms.
 482
 483 [table Process topologies
 484   [[C Function/Constant] [Boost.MPI Equivalent]]
 485
 486   [[`MPI_GRAPH`] [unnecessary; use [memberref boost::mpi::communicator::as_graph_communicator `communicator::as_graph_communicator`]]]
 487   [[`MPI_CART`] [unnecessary; use [memberref boost::mpi::communicator::has_cartesian_topology `communicator::has_cartesian_topology`]]]
 488
 489   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node133.html#Node133
 490   `MPI_Cart_create`]] [[classref boost::mpi::cartesian_communicator `cartesian_communicator`]
 491   constructor]]
 492   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node134.html#Node134
 493   `MPI_Dims_create`]] [[funcref boost::mpi::cartesian_dimensions `cartesian_dimensions`]]]
 494   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node135.html#Node135
 495   `MPI_Graph_create`]] [[classref
 496   boost::mpi::graph_communicator
 497   `graph_communicator ctors`]]]
 498   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 499   `MPI_Topo_test`]] [[memberref
 500   boost::mpi::communicator::as_graph_communicator
 501   `communicator::as_graph_communicator`], [memberref
 502   boost::mpi::communicator::has_cartesian_topology
 503   `communicator::has_cartesian_topology`]]]
 504   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 505   `MPI_Graphdims_get`]] [[funcref boost::mpi::num_vertices
 506   `num_vertices`], [funcref boost::mpi::num_edges `num_edges`]]]
 507   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 508   `MPI_Graph_get`]] [[funcref boost::mpi::vertices
 509   `vertices`], [funcref boost::mpi::edges `edges`]]]
 510   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 511   `MPI_Cartdim_get`]] [[memberref boost::mpi::cartesian_communicator::ndims `cartesian_communicator::ndims` ]]]
 512   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 513   `MPI_Cart_get`]] [[memberref boost::mpi::cartesian_communicator::topology `cartesian_communicator::topology` ]]]
 514   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 515   `MPI_Cart_rank`]] [[memberref boost::mpi::cartesian_communicator::rank `cartesian_communicator::rank` ]]]
 516   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 517   `MPI_Cart_coords`]] [[memberref boost::mpi::cartesian_communicator::coordinates `cartesian_communicator::coordinates` ]]]
 518   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 519   `MPI_Graph_neighbors_count`]] [[funcref boost::mpi::out_degree
 520   `out_degree`]]]
 521   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node136.html#Node136
 522   `MPI_Graph_neighbors`]] [[funcref boost::mpi::out_edges
 523   `out_edges`], [funcref boost::mpi::adjacent_vertices `adjacent_vertices`]]]
 524   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node137.html#Node137
 525   `MPI_Cart_shift`]] [[memberref boost::mpi::cartesian_communicator::shifted_ranks `cartesian_communicator::shifted_ranks` ]]]
 526   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node138.html#Node138
 527   `MPI_Cart_sub`]]  [[classref boost::mpi::cartesian_communicator `cartesian_communicator`]
 528   constructor]]
 529   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node139.html#Node139
 530   `MPI_Cart_map`]] [unsupported]]
 531   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node139.html#Node139
 532   `MPI_Graph_map`]] [unsupported]]
 533 ]
 534
 535 Boost.MPI supports environmental inquires through the [classref
 536 boost::mpi::environment `environment`] class.
 537
 538 [table Environmental inquiries
 539   [[C Function/Constant] [Boost.MPI Equivalent]]
 540
 541   [[`MPI_TAG_UB`] [unnecessary; use [memberref
 542   boost::mpi::environment::max_tag `environment::max_tag`]]]
 543   [[`MPI_HOST`] [unnecessary; use [memberref
 544   boost::mpi::environment::host_rank `environment::host_rank`]]]
 545   [[`MPI_IO`] [unnecessary; use [memberref
 546   boost::mpi::environment::io_rank `environment::io_rank`]]]
 547   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node143.html#Node147
 548   `MPI_Get_processor_name`]]
 549   [[memberref boost::mpi::environment::processor_name
 550   `environment::processor_name`]]]
 551 ]
 552
 553 Boost.MPI translates MPI errors into exceptions, reported via the
 554 [classref boost::mpi::exception `exception`] class.
 555
 556 [table Error handling
 557   [[C Function/Constant] [Boost.MPI Equivalent]]
 558
 559   [[`MPI_ERRORS_ARE_FATAL`] [unused; errors are translated into
 560   Boost.MPI exceptions]]
 561   [[`MPI_ERRORS_RETURN`] [unused; errors are translated into
 562   Boost.MPI exceptions]]
 563   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node148.html#Node148
 564   `MPI_errhandler_create`]] [unused; errors are translated into
 565   Boost.MPI exceptions]]
 566   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node148.html#Node148
 567   `MPI_errhandler_set`]] [unused; errors are translated into
 568   Boost.MPI exceptions]]
 569   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node148.html#Node148
 570   `MPI_errhandler_get`]] [unused; errors are translated into
 571   Boost.MPI exceptions]]
 572   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node148.html#Node148
 573   `MPI_errhandler_free`]] [unused; errors are translated into
 574   Boost.MPI exceptions]]
 575   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node148.html#Node148
 576   `MPI_Error_string`]] [used internally by Boost.MPI]]
 577   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node149.html#Node149
 578   `MPI_Error_class`]] [[memberref boost::mpi::exception::error_class `exception::error_class`]]]
 579 ]
 580
 581 The MPI timing facilities are exposed via the Boost.MPI [classref
 582 boost::mpi::timer `timer`] class, which provides an interface
 583 compatible with the [@http://www.boost.org/libs/timer/index.html Boost
 584 Timer library].
 585
 586 [table Timing facilities
 587   [[C Function/Constant] [Boost.MPI Equivalent]]
 588
 589   [[`MPI_WTIME_IS_GLOBAL`] [unnecessary; use [memberref
 590   boost::mpi::timer::time_is_global `timer::time_is_global`]]]
 591   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node150.html#Node150
 592   `MPI_Wtime`]] [use [memberref boost::mpi::timer::elapsed
 593   `timer::elapsed`] to determine the time elapsed from some specific
 594   starting point]]
 595   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node150.html#Node150
 596   `MPI_Wtick`]] [[memberref boost::mpi::timer::elapsed_min `timer::elapsed_min`]]]
 597 ]
 598
 599 MPI startup and shutdown are managed by the construction and
 600 destruction of the Boost.MPI [classref boost::mpi::environment
 601 `environment`] class.
 602
 603 [table Startup/shutdown facilities
 604   [[C Function] [Boost.MPI Equivalent]]
 605
 606   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node151.html#Node151
 607   `MPI_Init`]] [[classref boost::mpi::environment `environment`]
 608   constructor]]
 609   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node151.html#Node151
 610   `MPI_Finalize`]] [[classref boost::mpi::environment `environment`]
 611   destructor]]
 612  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node151.html#Node151
 613   `MPI_Initialized`]] [[memberref boost::mpi::environment::initialized
 614   `environment::initialized`]]]
 615  [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node151.html#Node151
 616   `MPI_Abort`]] [[memberref boost::mpi::environment::abort
 617   `environment::abort`]]]
 618 ]
 619
 620 Boost.MPI does not provide any support for the profiling facilities in
 621 MPI 1.1.
 622
 623 [table Profiling interface
 624   [[C Function] [Boost.MPI Equivalent]]
 625
 626   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node153.html#Node153
 627   `PMPI_*` routines]] [unsupported]]
 628   [[[@http://www.mpi-forum.org/docs/mpi-1.1/mpi-11-html/node156.html#Node156
 629   `MPI_Pcontrol`]] [unsupported]]
 630 ]
 631
 632 [endsect:c_mapping]