boost/mpi/communicator.hpp

   1 // Copyright (C) 2005, 2006 Douglas Gregor <doug.gregor -at- gmail.com>.
   2 // Copyright (C) 2016 K. Noel Belcourt <kbelco -at- sandia.gov>.
   3
   4 // Use, modification and distribution is subject to the Boost Software
   5 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   6 // http://www.boost.org/LICENSE_1_0.txt)
   7
   8 /** @file communicator.hpp
   9  *
  10  *  This header defines the @c communicator class, which is the basis
  11  *  of all communication within Boost.MPI, and provides point-to-point
  12  *  communication operations.
  13  */
  14 #ifndef BOOST_MPI_COMMUNICATOR_HPP
  15 #define BOOST_MPI_COMMUNICATOR_HPP
  16
  17 #include <boost/assert.hpp>
  18 #include <boost/mpi/config.hpp>
  19 #include <boost/mpi/exception.hpp>
  20 #include <boost/optional.hpp>
  21 #include <boost/shared_ptr.hpp>
  22 #include <boost/mpi/datatype.hpp>
  23 #include <boost/mpi/nonblocking.hpp>
  24 #include <boost/static_assert.hpp>
  25 #include <utility>
  26 #include <iterator>
  27 #include <stdexcept> // for std::range_error
  28 #include <vector>
  29
  30 // For (de-)serializing sends and receives
  31 #include <boost/mpi/packed_oarchive.hpp>
  32 #include <boost/mpi/packed_iarchive.hpp>
  33
  34 // For (de-)serializing skeletons and content
  35 #include <boost/mpi/skeleton_and_content_fwd.hpp>
  36
  37 #include <boost/mpi/detail/point_to_point.hpp>
  38 #include <boost/mpi/status.hpp>
  39 #include <boost/mpi/request.hpp>
  40
  41 #ifdef BOOST_MSVC
  42 #  pragma warning(push)
  43 #  pragma warning(disable : 4800) // forcing to bool 'true' or 'false'
  44 #endif
  45
  46 namespace boost { namespace mpi {
  47
  48 /**
  49  * @brief A constant representing "any process."
  50  *
  51  * This constant may be used for the @c source parameter of @c receive
  52  * operations to indicate that a message may be received from any
  53  * source.
  54  */
  55 const int any_source = MPI_ANY_SOURCE;
  56
  57 /**
  58  * @brief A constant representing "any tag."
  59  *
  60  * This constant may be used for the @c tag parameter of @c receive
  61  * operations to indicate that a @c send with any tag will be matched
  62  * by the receive.
  63  */
  64 const int any_tag = MPI_ANY_TAG;
  65
  66 /**
  67  * @brief Enumeration used to describe how to adopt a C @c MPI_Comm into
  68  * a Boost.MPI communicator.
  69  *
  70  * The values for this enumeration determine how a Boost.MPI
  71  * communicator will behave when constructed with an MPI
  72  * communicator. The options are:
  73  *
  74  *   - @c comm_duplicate: Duplicate the MPI_Comm communicator to
  75  *   create a new communicator (e.g., with MPI_Comm_dup). This new
  76  *   MPI_Comm communicator will be automatically freed when the
  77  *   Boost.MPI communicator (and all copies of it) is destroyed.
  78  *
  79  *   - @c comm_take_ownership: Take ownership of the communicator. It
  80  *   will be freed automatically when all of the Boost.MPI
  81  *   communicators go out of scope. This option must not be used with
  82  *   MPI_COMM_WORLD.
  83  *
  84  *   - @c comm_attach: The Boost.MPI communicator will reference the
  85  *   existing MPI communicator but will not free it when the Boost.MPI
  86  *   communicator goes out of scope. This option should only be used
  87  *   when the communicator is managed by the user or MPI library
  88  *   (e.g., MPI_COMM_WORLD).
  89  */
  90 enum comm_create_kind { comm_duplicate, comm_take_ownership, comm_attach };
  91
  92 /**
  93  * INTERNAL ONLY
  94  *
  95  * Forward declaration of @c group needed for the @c group
  96  * constructor and accessor.
  97  */
  98 class group;
  99
 100 /**
 101  * INTERNAL ONLY
 102  *
 103  * Forward declaration of @c intercommunicator needed for the "cast"
 104  * from a communicator to an intercommunicator.
 105  */
 106 class intercommunicator;
 107
 108 /**
 109  * INTERNAL ONLY
 110  *
 111  * Forward declaration of @c graph_communicator needed for the "cast"
 112  * from a communicator to a graph communicator.
 113  */
 114 class graph_communicator;
 115
 116 /**
 117  * INTERNAL ONLY
 118  *
 119  * Forward declaration of @c cartesian_communicator needed for the "cast"
 120  * from a communicator to a cartesian communicator.
 121  */
 122 class cartesian_communicator;
 123
 124 /**
 125  * @brief A communicator that permits communication and
 126  * synchronization among a set of processes.
 127  *
 128  * The @c communicator class abstracts a set of communicating
 129  * processes in MPI. All of the processes that belong to a certain
 130  * communicator can determine the size of the communicator, their rank
 131  * within the communicator, and communicate with any other processes
 132  * in the communicator.
 133  */
 134 class BOOST_MPI_DECL communicator
 135 {
 136  public:
 137   /**
 138    * Build a new Boost.MPI communicator for @c MPI_COMM_WORLD.
 139    *
 140    * Constructs a Boost.MPI communicator that attaches to @c
 141    * MPI_COMM_WORLD. This is the equivalent of constructing with
 142    * @c (MPI_COMM_WORLD, comm_attach).
 143    */
 144   communicator();
 145
 146   /**
 147    * Build a new Boost.MPI communicator based on the MPI communicator
 148    * @p comm.
 149    *
 150    * @p comm may be any valid MPI communicator. If @p comm is
 151    * MPI_COMM_NULL, an empty communicator (that cannot be used for
 152    * communication) is created and the @p kind parameter is
 153    * ignored. Otherwise, the @p kind parameters determines how the
 154    * Boost.MPI communicator will be related to @p comm:
 155    *
 156    *   - If @p kind is @c comm_duplicate, duplicate @c comm to create
 157    *   a new communicator. This new communicator will be freed when
 158    *   the Boost.MPI communicator (and all copies of it) is destroyed.
 159    *   This option is only permitted if @p comm is a valid MPI
 160    *   intracommunicator or if the underlying MPI implementation
 161    *   supports MPI 2.0 (which supports duplication of
 162    *   intercommunicators).
 163    *
 164    *   - If @p kind is @c comm_take_ownership, take ownership of @c
 165    *   comm. It will be freed automatically when all of the Boost.MPI
 166    *   communicators go out of scope. This option must not be used
 167    *   when @c comm is MPI_COMM_WORLD.
 168    *
 169    *   - If @p kind is @c comm_attach, this Boost.MPI communicator
 170    *   will reference the existing MPI communicator @p comm but will
 171    *   not free @p comm when the Boost.MPI communicator goes out of
 172    *   scope. This option should only be used when the communicator is
 173    *   managed by the user or MPI library (e.g., MPI_COMM_WORLD).
 174    */
 175   communicator(const MPI_Comm& comm, comm_create_kind kind);
 176
 177   /**
 178    * Build a new Boost.MPI communicator based on a subgroup of another
 179    * MPI communicator.
 180    *
 181    * This routine will construct a new communicator containing all of
 182    * the processes from communicator @c comm that are listed within
 183    * the group @c subgroup. Equivalent to @c MPI_Comm_create.
 184    *
 185    * @param comm An MPI communicator.
 186    *
 187    * @param subgroup A subgroup of the MPI communicator, @p comm, for
 188    * which we will construct a new communicator.
 189    */
 190   communicator(const communicator& comm, const boost::mpi::group& subgroup);
 191
 192   /**
 193    * @brief Determine the rank of the executing process in a
 194    * communicator.
 195    *
 196    * This routine is equivalent to @c MPI_Comm_rank.
 197    *
 198    *   @returns The rank of the process in the communicator, which
 199    *   will be a value in [0, size())
 200    */
 201   int rank() const;
 202
 203   /**
 204    * @brief Determine the number of processes in a communicator.
 205    *
 206    * This routine is equivalent to @c MPI_Comm_size.
 207    *
 208    *   @returns The number of processes in the communicator.
 209    */
 210   int size() const;
 211
 212   /**
 213    * This routine constructs a new group whose members are the
 214    * processes within this communicator. Equivalent to
 215    * calling @c MPI_Comm_group.
 216    */
 217   boost::mpi::group group() const;
 218
 219   // ----------------------------------------------------------------
 220   // Point-to-point communication
 221   // ----------------------------------------------------------------
 222
 223   /**
 224    *  @brief Send data to another process.
 225    *
 226    *  This routine executes a potentially blocking send with tag @p tag
 227    *  to the process with rank @p dest. It can be received by the
 228    *  destination process with a matching @c recv call.
 229    *
 230    *  The given @p value must be suitable for transmission over
 231    *  MPI. There are several classes of types that meet these
 232    *  requirements:
 233    *
 234    *    - Types with mappings to MPI data types: If @c
 235    *    is_mpi_datatype<T> is convertible to @c mpl::true_, then @p
 236    *    value will be transmitted using the MPI data type
 237    *    @c get_mpi_datatype<T>(). All primitive C++ data types that have
 238    *    MPI equivalents, e.g., @c int, @c float, @c char, @c double,
 239    *    etc., have built-in mappings to MPI data types. You may turn a
 240    *    Serializable type with fixed structure into an MPI data type by
 241    *    specializing @c is_mpi_datatype for your type.
 242    *
 243    *    - Serializable types: Any type that provides the @c serialize()
 244    *    functionality required by the Boost.Serialization library can be
 245    *    transmitted and received.
 246    *
 247    *    - Packed archives and skeletons: Data that has been packed into
 248    *    an @c mpi::packed_oarchive or the skeletons of data that have
 249    *    been backed into an @c mpi::packed_skeleton_oarchive can be
 250    *    transmitted, but will be received as @c mpi::packed_iarchive and
 251    *    @c mpi::packed_skeleton_iarchive, respectively, to allow the
 252    *    values (or skeletons) to be extracted by the destination process.
 253    *
 254    *    - Content: Content associated with a previously-transmitted
 255    *    skeleton can be transmitted by @c send and received by @c
 256    *    recv. The receiving process may only receive content into the
 257    *    content of a value that has been constructed with the matching
 258    *    skeleton.
 259    *
 260    *  For types that have mappings to an MPI data type (including the
 261    *  concent of a type), an invocation of this routine will result in
 262    *  a single MPI_Send call. For variable-length data, e.g.,
 263    *  serialized types and packed archives, two messages will be sent
 264    *  via MPI_Send: one containing the length of the data and the
 265    *  second containing the data itself.
 266    *
 267    *  Std::vectors of MPI data type
 268    *  are considered variable size, e.g. their number of elements is
 269    *  unknown and must be transmited (although the serialization process
 270    *  is skipped). You can use the array specialized versions of
 271    *  communication methods is both sender and receiver know the vector
 272    *  size.
 273    *
 274    *  Note that the transmission mode for variable-length data is an
 275    *  implementation detail that is subject to change.
 276    *
 277    *  @param dest The rank of the remote process to which the data
 278    *  will be sent.
 279    *
 280    *  @param tag The tag that will be associated with this message. Tags
 281    *  may be any integer between zero and an implementation-defined
 282    *  upper limit. This limit is accessible via @c environment::max_tag().
 283    *
 284    *  @param value The value that will be transmitted to the
 285    *  receiver. The type @c T of this value must meet the aforementioned
 286    *  criteria for transmission.
 287    */
 288   template<typename T>
 289   void send(int dest, int tag, const T& value) const;
 290
 291   template<typename T, typename A>
 292   void send(int dest, int tag, const std::vector<T,A>& value) const;
 293
 294   /**
 295    *  @brief Send the skeleton of an object.
 296    *
 297    *  This routine executes a potentially blocking send with tag @p
 298    *  tag to the process with rank @p dest. It can be received by the
 299    *  destination process with a matching @c recv call. This variation
 300    *  on @c send will be used when a send of a skeleton is explicitly
 301    *  requested via code such as:
 302    *
 303    *  @code
 304    *    comm.send(dest, tag, skeleton(object));
 305    *  @endcode
 306    *
 307    *  The semantics of this routine are equivalent to that of sending
 308    *  a @c packed_skeleton_oarchive storing the skeleton of the @c
 309    *  object.
 310    *
 311    *  @param dest The rank of the remote process to which the skeleton
 312    *  will be sent.
 313    *
 314    *  @param tag The tag that will be associated with this message. Tags
 315    *  may be any integer between zero and an implementation-defined
 316    *  upper limit. This limit is accessible via @c environment::max_tag().
 317    *
 318    *  @param proxy The @c skeleton_proxy containing a reference to the
 319    *  object whose skeleton will be transmitted.
 320    *
 321    */
 322   template<typename T>
 323   void send(int dest, int tag, const skeleton_proxy<T>& proxy) const;
 324
 325   /**
 326    *  @brief Send an array of values to another process.
 327    *
 328    *  This routine executes a potentially blocking send of an array of
 329    *  data with tag @p tag to the process with rank @p dest. It can be
 330    *  received by the destination process with a matching array @c
 331    *  recv call.
 332    *
 333    *  If @c T is an MPI datatype, an invocation of this routine will
 334    *  be mapped to a single call to MPI_Send, using the datatype @c
 335    *  get_mpi_datatype<T>().
 336    *
 337    *  @param dest The process rank of the remote process to which
 338    *  the data will be sent.
 339    *
 340    *  @param tag The tag that will be associated with this message. Tags
 341    *  may be any integer between zero and an implementation-defined
 342    *  upper limit. This limit is accessible via @c environment::max_tag().
 343    *
 344    *  @param values The array of values that will be transmitted to the
 345    *  receiver. The type @c T of these values must be mapped to an MPI
 346    *  data type.
 347    *
 348    *  @param n The number of values stored in the array. The destination
 349    *  process must call receive with at least this many elements to
 350    *  correctly receive the message.
 351    */
 352   template<typename T>
 353   void send(int dest, int tag, const T* values, int n) const;
 354
 355   /**
 356    *  @brief Send a message to another process without any data.
 357    *
 358    *  This routine executes a potentially blocking send of a message
 359    *  to another process. The message contains no extra data, and can
 360    *  therefore only be received by a matching call to @c recv().
 361    *
 362    *  @param dest The process rank of the remote process to which
 363    *  the message will be sent.
 364    *
 365    *  @param tag The tag that will be associated with this message. Tags
 366    *  may be any integer between zero and an implementation-defined
 367    *  upper limit. This limit is accessible via @c environment::max_tag().
 368    *
 369    */
 370   void send(int dest, int tag) const;
 371
 372   /**
 373    * @brief Receive data from a remote process.
 374    *
 375    * This routine blocks until it receives a message from the process @p
 376    * source with the given @p tag. The type @c T of the @p value must be
 377    * suitable for transmission over MPI, which includes serializable
 378    * types, types that can be mapped to MPI data types (including most
 379    * built-in C++ types), packed MPI archives, skeletons, and content
 380    * associated with skeletons; see the documentation of @c send for a
 381    * complete description.
 382    *
 383    *   @param source The process that will be sending data. This will
 384    *   either be a process rank within the communicator or the
 385    *   constant @c any_source, indicating that we can receive the
 386    *   message from any process.
 387    *
 388    *   @param tag The tag that matches a particular kind of message sent
 389    *   by the source process. This may be any tag value permitted by @c
 390    *   send. Alternatively, the argument may be the constant @c any_tag,
 391    *   indicating that this receive matches a message with any tag.
 392    *
 393    *   @param value Will contain the value of the message after a
 394    *   successful receive. The type of this value must match the value
 395    *   transmitted by the sender, unless the sender transmitted a packed
 396    *   archive or skeleton: in these cases, the sender transmits a @c
 397    *   packed_oarchive or @c packed_skeleton_oarchive and the
 398    *   destination receives a @c packed_iarchive or @c
 399    *   packed_skeleton_iarchive, respectively.
 400    *
 401    *   @returns Information about the received message.
 402    */
 403   template<typename T>
 404   status recv(int source, int tag, T& value) const;
 405
 406   template<typename T, typename A>
 407   status recv(int source, int tag, std::vector<T,A>& value) const;
 408
 409   /**
 410    *  @brief Receive a skeleton from a remote process.
 411    *
 412    *  This routine blocks until it receives a message from the process @p
 413    *  source with the given @p tag containing a skeleton.
 414    *
 415    *  @param source The process that will be sending data. This will
 416    *  either be a process rank within the communicator or the constant
 417    *  @c any_source, indicating that we can receive the message from
 418    *  any process.
 419    *
 420    *  @param tag The tag that matches a particular kind of message
 421    *  sent by the source process. This may be any tag value permitted
 422    *  by @c send. Alternatively, the argument may be the constant @c
 423    *  any_tag, indicating that this receive matches a message with any
 424    *  tag.
 425    *
 426    *  @param proxy The @c skeleton_proxy containing a reference to the
 427    *  object that will be reshaped to match the received skeleton.
 428    *
 429    *  @returns Information about the received message.
 430    */
 431   template<typename T>
 432   status recv(int source, int tag, const skeleton_proxy<T>& proxy) const;
 433
 434   /**
 435    *  @brief Receive a skeleton from a remote process.
 436    *
 437    *  This routine blocks until it receives a message from the process @p
 438    *  source with the given @p tag containing a skeleton.
 439    *
 440    *  @param source The process that will be sending data. This will
 441    *  either be a process rank within the communicator or the constant
 442    *  @c any_source, indicating that we can receive the message from
 443    *  any process.
 444    *
 445    *  @param tag The tag that matches a particular kind of message
 446    *  sent by the source process. This may be any tag value permitted
 447    *  by @c send. Alternatively, the argument may be the constant @c
 448    *  any_tag, indicating that this receive matches a message with any
 449    *  tag.
 450    *
 451    *  @param proxy The @c skeleton_proxy containing a reference to the
 452    *  object that will be reshaped to match the received skeleton.
 453    *
 454    *  @returns Information about the received message.
 455    */
 456   template<typename T>
 457   status recv(int source, int tag, skeleton_proxy<T>& proxy) const;
 458
 459   /**
 460    * @brief Receive an array of values from a remote process.
 461    *
 462    * This routine blocks until it receives an array of values from the
 463    * process @p source with the given @p tag. If the type @c T is
 464    *
 465    *   @param source The process that will be sending data. This will
 466    *   either be a process rank within the communicator or the
 467    *   constant @c any_source, indicating that we can receive the
 468    *   message from any process.
 469    *
 470    *   @param tag The tag that matches a particular kind of message sent
 471    *   by the source process. This may be any tag value permitted by @c
 472    *   send. Alternatively, the argument may be the constant @c any_tag,
 473    *   indicating that this receive matches a message with any tag.
 474    *
 475    *   @param values Will contain the values in the message after a
 476    *   successful receive. The type of these elements must match the
 477    *   type of the elements transmitted by the sender.
 478    *
 479    *   @param n The number of values that can be stored into the @p
 480    *   values array. This shall not be smaller than the number of
 481    *   elements transmitted by the sender.
 482    *
 483    *   @throws std::range_error if the message to be received contains
 484    *   more than @p n values.
 485    *
 486    *   @returns Information about the received message.
 487    */
 488   template<typename T>
 489   status recv(int source, int tag, T* values, int n) const;
 490
 491   /**
 492    *  @brief Receive a message from a remote process without any data.
 493    *
 494    *  This routine blocks until it receives a message from the process
 495    *  @p source with the given @p tag.
 496    *
 497    *  @param source The process that will be sending the message. This
 498    *  will either be a process rank within the communicator or the
 499    *  constant @c any_source, indicating that we can receive the
 500    *  message from any process.
 501    *
 502    *  @param tag The tag that matches a particular kind of message
 503    *  sent by the source process. This may be any tag value permitted
 504    *  by @c send. Alternatively, the argument may be the constant @c
 505    *  any_tag, indicating that this receive matches a message with any
 506    *  tag.
 507    *
 508    *  @returns Information about the received message.
 509    */
 510   status recv(int source, int tag) const;
 511
 512   /** @brief Send a message to remote process and receive another message
 513    *  from another process.
 514    */
 515   template<typename T>
 516   status sendrecv(int dest, int stag, const T& sval, int src, int rtag, T& rval) const;
 517
 518   /**
 519    *  @brief Send a message to a remote process without blocking.
 520    *
 521    *  The @c isend method is functionality identical to the @c send
 522    *  method and transmits data in the same way, except that @c isend
 523    *  will not block while waiting for the data to be
 524    *  transmitted. Instead, a request object will be immediately
 525    *  returned, allowing one to query the status of the communication
 526    *  or wait until it has completed.
 527    *
 528    *  @param dest The rank of the remote process to which the data
 529    *  will be sent.
 530    *
 531    *  @param tag The tag that will be associated with this message. Tags
 532    *  may be any integer between zero and an implementation-defined
 533    *  upper limit. This limit is accessible via @c environment::max_tag().
 534    *
 535    *  @param value The value that will be transmitted to the
 536    *  receiver. The type @c T of this value must meet the aforementioned
 537    *  criteria for transmission. If modified before transmited, the
 538    *  modification may or may not be transmited.
 539    *
 540    *  @returns a @c request object that describes this communication.
 541    */
 542   template<typename T>
 543   request isend(int dest, int tag, const T& value) const;
 544
 545   /**
 546    *  @brief Send the skeleton of an object without blocking.
 547    *
 548    *  This routine is functionally identical to the @c send method for
 549    *  @c skeleton_proxy objects except that @c isend will not block
 550    *  while waiting for the data to be transmitted. Instead, a request
 551    *  object will be immediately returned, allowing one to query the
 552    *  status of the communication or wait until it has completed.
 553    *
 554    *  The semantics of this routine are equivalent to a non-blocking
 555    *  send of a @c packed_skeleton_oarchive storing the skeleton of
 556    *  the @c object.
 557    *
 558    *  @param dest The rank of the remote process to which the skeleton
 559    *  will be sent.
 560    *
 561    *  @param tag The tag that will be associated with this message. Tags
 562    *  may be any integer between zero and an implementation-defined
 563    *  upper limit. This limit is accessible via @c environment::max_tag().
 564    *
 565    *  @param proxy The @c skeleton_proxy containing a reference to the
 566    *  object whose skeleton will be transmitted.
 567    *
 568    *  @returns a @c request object that describes this communication.
 569    */
 570   template<typename T>
 571   request isend(int dest, int tag, const skeleton_proxy<T>& proxy) const;
 572
 573   /**
 574    *  @brief Send an array of values to another process without
 575    *  blocking.
 576    *
 577    *  This routine is functionally identical to the @c send method for
 578    *  arrays except that @c isend will not block while waiting for the
 579    *  data to be transmitted. Instead, a request object will be
 580    *  immediately returned, allowing one to query the status of the
 581    *  communication or wait until it has completed.
 582    *
 583    *  @param dest The process rank of the remote process to which
 584    *  the data will be sent.
 585    *
 586    *  @param tag The tag that will be associated with this message. Tags
 587    *  may be any integer between zero and an implementation-defined
 588    *  upper limit. This limit is accessible via @c environment::max_tag().
 589    *
 590    *  @param values The array of values that will be transmitted to the
 591    *  receiver. The type @c T of these values must be mapped to an MPI
 592    *  data type.
 593    *
 594    *  @param n The number of values stored in the array. The destination
 595    *  process must call receive with at least this many elements to
 596    *  correctly receive the message.
 597    *
 598    *  @returns a @c request object that describes this communication.
 599    */
 600   template<typename T>
 601   request isend(int dest, int tag, const T* values, int n) const;
 602
 603   template<typename T, class A>
 604   request isend(int dest, int tag, const std::vector<T,A>& values) const;
 605
 606   /**
 607    *  @brief Send a message to another process without any data
 608    *  without blocking.
 609    *
 610    *  This routine is functionally identical to the @c send method for
 611    *  sends with no data, except that @c isend will not block while
 612    *  waiting for the message to be transmitted. Instead, a request
 613    *  object will be immediately returned, allowing one to query the
 614    *  status of the communication or wait until it has completed.
 615    *
 616    *  @param dest The process rank of the remote process to which
 617    *  the message will be sent.
 618    *
 619    *  @param tag The tag that will be associated with this message. Tags
 620    *  may be any integer between zero and an implementation-defined
 621    *  upper limit. This limit is accessible via @c environment::max_tag().
 622    *
 623    *
 624    *  @returns a @c request object that describes this communication.
 625    */
 626   request isend(int dest, int tag) const;
 627
 628   /**
 629    *  @brief Prepare to receive a message from a remote process.
 630    *
 631    *  The @c irecv method is functionally identical to the @c recv
 632    *  method and receive data in the same way, except that @c irecv
 633    *  will not block while waiting for data to be
 634    *  transmitted. Instead, it immediately returns a request object
 635    *  that allows one to query the status of the receive or wait until
 636    *  it has completed.
 637    *
 638    *   @param source The process that will be sending data. This will
 639    *   either be a process rank within the communicator or the
 640    *   constant @c any_source, indicating that we can receive the
 641    *   message from any process.
 642    *
 643    *   @param tag The tag that matches a particular kind of message sent
 644    *   by the source process. This may be any tag value permitted by @c
 645    *   send. Alternatively, the argument may be the constant @c any_tag,
 646    *   indicating that this receive matches a message with any tag.
 647    *
 648    *   @param value Will contain the value of the message after a
 649    *   successful receive. The type of this value must match the value
 650    *   transmitted by the sender, unless the sender transmitted a packed
 651    *   archive or skeleton: in these cases, the sender transmits a @c
 652    *   packed_oarchive or @c packed_skeleton_oarchive and the
 653    *   destination receives a @c packed_iarchive or @c
 654    *   packed_skeleton_iarchive, respectively.
 655    *
 656    *   @returns a @c request object that describes this communication.
 657    */
 658   template<typename T>
 659   request irecv(int source, int tag, T& value) const;
 660
 661   /**
 662    * @brief Initiate receipt of an array of values from a remote process.
 663    *
 664    * This routine initiates a receive operation for an array of values
 665    * transmitted by process @p source with the given @p tag.
 666    *
 667    *    @param source The process that will be sending data. This will
 668    *    either be a process rank within the communicator or the
 669    *    constant @c any_source, indicating that we can receive the
 670    *    message from any process.
 671    *
 672    *    @param tag The tag that matches a particular kind of message sent
 673    *    by the source process. This may be any tag value permitted by @c
 674    *    send. Alternatively, the argument may be the constant @c any_tag,
 675    *    indicating that this receive matches a message with any tag.
 676    *
 677    *    @param values Will contain the values in the message after a
 678    *    successful receive. The type of these elements must match the
 679    *    type of the elements transmitted by the sender.
 680    *
 681    *    @param n The number of values that can be stored into the @p
 682    *    values array. This shall not be smaller than the number of
 683    *    elements transmitted by the sender.
 684    *
 685    *    @returns a @c request object that describes this communication.
 686    */
 687   template<typename T>
 688   request irecv(int source, int tag, T* values, int n) const;
 689
 690   template<typename T, typename A>
 691   request irecv(int source, int tag, std::vector<T,A>& values) const;
 692
 693   /**
 694    *  @brief Initiate receipt of a message from a remote process that
 695    *  carries no data.
 696    *
 697    *  This routine initiates a receive operation for a message from
 698    *  process @p source with the given @p tag that carries no data.
 699    *
 700    *    @param source The process that will be sending the message. This
 701    *    will either be a process rank within the communicator or the
 702    *    constant @c any_source, indicating that we can receive the
 703    *    message from any process.
 704    *
 705    *    @param tag The tag that matches a particular kind of message
 706    *    sent by the source process. This may be any tag value permitted
 707    *    by @c send. Alternatively, the argument may be the constant @c
 708    *    any_tag, indicating that this receive matches a message with any
 709    *    tag.
 710    *
 711    *    @returns a @c request object that describes this communication.
 712    */
 713   request irecv(int source, int tag) const;
 714
 715   /**
 716    * @brief Waits until a message is available to be received.
 717    *
 718    * This operation waits until a message matching (@p source, @p tag)
 719    * is available to be received. It then returns information about
 720    * that message. The functionality is equivalent to @c MPI_Probe. To
 721    * check if a message is available without blocking, use @c iprobe.
 722    *
 723    *   @param source Determine if there is a message available from
 724    *   this rank. If @c any_source, then the message returned may come
 725    *   from any source.
 726    *
 727    *   @param tag Determine if there is a message available with the
 728    *   given tag. If @c any_tag, then the message returned may have any
 729    *   tag.
 730    *
 731    *   @returns Returns information about the first message that
 732    *   matches the given criteria.
 733    */
 734   status probe(int source = any_source, int tag = any_tag) const;
 735
 736   /**
 737    * @brief Determine if a message is available to be received.
 738    *
 739    * This operation determines if a message matching (@p source, @p
 740    * tag) is available to be received. If so, it returns information
 741    * about that message; otherwise, it returns immediately with an
 742    * empty optional. The functionality is equivalent to @c
 743    * MPI_Iprobe. To wait until a message is available, use @c wait.
 744    *
 745    *   @param source Determine if there is a message available from
 746    *   this rank. If @c any_source, then the message returned may come
 747    *   from any source.
 748    *
 749    *   @param tag Determine if there is a message available with the
 750    *   given tag. If @c any_tag, then the message returned may have any
 751    *   tag.
 752    *
 753    *   @returns If a matching message is available, returns
 754    *   information about that message. Otherwise, returns an empty
 755    *   @c boost::optional.
 756    */
 757   optional<status>
 758   iprobe(int source = any_source, int tag = any_tag) const;
 759
 760 #ifdef barrier
 761   // Linux defines a function-like macro named "barrier". So, we need
 762   // to avoid expanding the macro when we define our barrier()
 763   // function. However, some C++ parsers (Doxygen, for instance) can't
 764   // handle this syntax, so we only use it when necessary.
 765   void (barrier)() const;
 766 #else
 767   /**
 768    * @brief Wait for all processes within a communicator to reach the
 769    * barrier.
 770    *
 771    * This routine is a collective operation that blocks each process
 772    * until all processes have entered it, then releases all of the
 773    * processes "simultaneously". It is equivalent to @c MPI_Barrier.
 774    */
 775   void barrier() const;
 776 #endif
 777
 778   /** @brief Determine if this communicator is valid for
 779    * communication.
 780    *
 781    * Evaluates @c true in a boolean context if this communicator is
 782    * valid for communication, i.e., does not represent
 783    * MPI_COMM_NULL. Otherwise, evaluates @c false.
 784    */
 785   operator bool() const { return (bool)comm_ptr; }
 786
 787   /**
 788    * @brief Access the MPI communicator associated with a Boost.MPI
 789    * communicator.
 790    *
 791    * This routine permits the implicit conversion from a Boost.MPI
 792    * communicator to an MPI communicator.
 793    *
 794    *   @returns The associated MPI communicator.
 795    */
 796   operator MPI_Comm() const;
 797
 798   /**
 799    * Split the communicator into multiple, disjoint communicators
 800    * each of which is based on a particular color. This is a
 801    * collective operation that returns a new communicator that is a
 802    * subgroup of @p this.
 803    *
 804    *   @param color The color of this process. All processes with the
 805    *   same @p color value will be placed into the same group.
 806    *
 807    *   @param key A key value that will be used to determine the
 808    *   ordering of processes with the same color in the resulting
 809    *   communicator. If omitted, the rank of the processes in @p this
 810    *   will determine the ordering of processes in the resulting
 811    *   group.
 812    *
 813    *   @returns A new communicator containing all of the processes in
 814    *   @p this that have the same @p color.
 815    */
 816   communicator split(int color, int key) const;
 817   communicator split(int color) const;
 818
 819   /**
 820    * Determine if the communicator is in fact an intercommunicator
 821    * and, if so, return that intercommunicator.
 822    *
 823    * @returns an @c optional containing the intercommunicator, if this
 824    * communicator is in fact an intercommunicator. Otherwise, returns
 825    * an empty @c optional.
 826    */
 827   optional<intercommunicator> as_intercommunicator() const;
 828
 829   /**
 830    * Determine if the communicator has a graph topology and, if so,
 831    * return that @c graph_communicator. Even though the communicators
 832    * have different types, they refer to the same underlying
 833    * communication space and can be used interchangeably for
 834    * communication.
 835    *
 836    * @returns an @c optional containing the graph communicator, if this
 837    * communicator does in fact have a graph topology. Otherwise, returns
 838    * an empty @c optional.
 839    */
 840   optional<graph_communicator> as_graph_communicator() const;
 841
 842   /**
 843    * Determines whether this communicator has a Graph topology.
 844    */
 845   bool has_graph_topology() const;
 846
 847   /**
 848    * Determine if the communicator has a cartesian topology and, if so,
 849    * return that @c cartesian_communicator. Even though the communicators
 850    * have different types, they refer to the same underlying
 851    * communication space and can be used interchangeably for
 852    * communication.
 853    *
 854    * @returns an @c optional containing the cartesian communicator, if this
 855    * communicator does in fact have a cartesian topology. Otherwise, returns
 856    * an empty @c optional.
 857    */
 858   optional<cartesian_communicator> as_cartesian_communicator() const;
 859
 860   /**
 861    * Determines whether this communicator has a Cartesian topology.
 862    */
 863   bool has_cartesian_topology() const;
 864
 865   /** Abort all tasks in the group of this communicator.
 866    *
 867    *  Makes a "best attempt" to abort all of the tasks in the group of
 868    *  this communicator. Depending on the underlying MPI
 869    *  implementation, this may either abort the entire program (and
 870    *  possibly return @p errcode to the environment) or only abort
 871    *  some processes, allowing the others to continue. Consult the
 872    *  documentation for your MPI implementation. This is equivalent to
 873    *  a call to @c MPI_Abort
 874    *
 875    *  @param errcode The error code to return from aborted processes.
 876    *  @returns Will not return.
 877    */
 878   void abort(int errcode) const;
 879
 880  protected:
 881
 882   /**
 883    * INTERNAL ONLY
 884    *
 885    * Implementation of sendrecv for mpi type.
 886    */
 887   template<typename T>
 888   status sendrecv_impl(int dest, int stag, const T& sval, int src, int rtag, T& rval,
 889                        mpl::true_) const;
 890
 891   /**
 892    * INTERNAL ONLY
 893    *
 894    * Implementation of sendrecv for complex types, which must be passed as archives.
 895    */
 896   template<typename T>
 897   status sendrecv_impl(int dest, int stag, const T& sval, int src, int rtag, T& rval,
 898                        mpl::false_) const;
 899
 900   /**
 901    * INTERNAL ONLY
 902    *
 903    * Function object that frees an MPI communicator and deletes the
 904    * memory associated with it. Intended to be used as a deleter with
 905    * shared_ptr.
 906    */
 907   struct comm_free
 908   {
 909     void operator()(MPI_Comm* comm) const
 910     {
 911       BOOST_ASSERT( comm != 0 );
 912       BOOST_ASSERT(*comm != MPI_COMM_NULL);
 913       int finalized;
 914       BOOST_MPI_CHECK_RESULT(MPI_Finalized, (&finalized));
 915       if (!finalized)
 916         BOOST_MPI_CHECK_RESULT(MPI_Comm_free, (comm));
 917       delete comm;
 918     }
 919   };
 920
 921
 922   /**
 923    * INTERNAL ONLY
 924    *
 925    * We're sending a type that has an associated MPI datatype, so we
 926    * map directly to that datatype.
 927    */
 928   template<typename T>
 929   void send_impl(int dest, int tag, const T& value, mpl::true_) const;
 930
 931   /**
 932    * INTERNAL ONLY
 933    *
 934    * We're sending a type that does not have an associated MPI
 935    * datatype, so it must be serialized then sent as MPI_PACKED data,
 936    * to be deserialized on the receiver side.
 937    */
 938   template<typename T>
 939   void send_impl(int dest, int tag, const T& value, mpl::false_) const;
 940
 941   /**
 942    * INTERNAL ONLY
 943    *
 944    * We're sending an array of a type that has an associated MPI
 945    * datatype, so we map directly to that datatype.
 946    */
 947   template<typename T>
 948   void
 949   array_send_impl(int dest, int tag, const T* values, int n, mpl::true_) const;
 950
 951   /**
 952    * INTERNAL ONLY
 953    *
 954    * We're sending an array of a type that does not have an associated
 955    * MPI datatype, so it must be serialized then sent as MPI_PACKED
 956    * data, to be deserialized on the receiver side.
 957    */
 958   template<typename T>
 959   void
 960   array_send_impl(int dest, int tag, const T* values, int n,
 961                   mpl::false_) const;
 962
 963   /**
 964    * INTERNAL ONLY
 965    *
 966    * We're sending a type that has an associated MPI datatype, so we
 967    * map directly to that datatype.
 968    */
 969   template<typename T>
 970   request isend_impl(int dest, int tag, const T& value, mpl::true_) const;
 971
 972   /**
 973    * INTERNAL ONLY
 974    *
 975    * We're sending a type that does not have an associated MPI
 976    * datatype, so it must be serialized then sent as MPI_PACKED data,
 977    * to be deserialized on the receiver side.
 978    */
 979   template<typename T>
 980   request isend_impl(int dest, int tag, const T& value, mpl::false_) const;
 981
 982   /**
 983    * INTERNAL ONLY
 984    *
 985    * We're sending an array of a type that has an associated MPI
 986    * datatype, so we map directly to that datatype.
 987    */
 988   template<typename T>
 989   request
 990   array_isend_impl(int dest, int tag, const T* values, int n,
 991                    mpl::true_) const;
 992
 993   /**
 994    * INTERNAL ONLY
 995    *
 996    * We're sending an array of a type that does not have an associated
 997    * MPI datatype, so it must be serialized then sent as MPI_PACKED
 998    * data, to be deserialized on the receiver side.
 999    */
1000   template<typename T>
1001   request
1002   array_isend_impl(int dest, int tag, const T* values, int n,
1003                    mpl::false_) const;
1004
1005   /**
1006    * INTERNAL ONLY
1007    *
1008    * We're receiving a type that has an associated MPI datatype, so we
1009    * map directly to that datatype.
1010    */
1011   template<typename T>
1012   status recv_impl(int source, int tag, T& value, mpl::true_) const;
1013
1014   /**
1015    * INTERNAL ONLY
1016    *
1017    * We're receiving a type that does not have an associated MPI
1018    * datatype, so it must have been serialized then sent as
1019    * MPI_PACKED. We'll receive it and then deserialize.
1020    */
1021   template<typename T>
1022   status recv_impl(int source, int tag, T& value, mpl::false_) const;
1023
1024   /**
1025    * INTERNAL ONLY
1026    *
1027    * We're receiving an array of a type that has an associated MPI
1028    * datatype, so we map directly to that datatype.
1029    */
1030   template<typename T>
1031   status
1032   array_recv_impl(int source, int tag, T* values, int n, mpl::true_) const;
1033
1034   /**
1035    * INTERNAL ONLY
1036    *
1037    * We're receiving a type that does not have an associated MPI
1038    * datatype, so it must have been serialized then sent as
1039    * MPI_PACKED. We'll receive it and then deserialize.
1040    */
1041   template<typename T>
1042   status
1043   array_recv_impl(int source, int tag, T* values, int n, mpl::false_) const;
1044
1045   /**
1046    * INTERNAL ONLY
1047    *
1048    * We're receiving a type that has an associated MPI datatype, so we
1049    * map directly to that datatype.
1050    */
1051   template<typename T>
1052   request irecv_impl(int source, int tag, T& value, mpl::true_) const;
1053
1054   /**
1055    * INTERNAL ONLY
1056    *
1057    * We're receiving a type that does not have an associated MPI
1058    * datatype, so it must have been serialized then sent as
1059    * MPI_PACKED. We'll receive it and then deserialize.
1060    */
1061   template<typename T>
1062   request irecv_impl(int source, int tag, T& value, mpl::false_) const;
1063
1064   /**
1065    * INTERNAL ONLY
1066    *
1067    * We're receiving a type that has an associated MPI datatype, so we
1068    * map directly to that datatype.
1069    */
1070   template<typename T>
1071   request
1072   array_irecv_impl(int source, int tag, T* values, int n, mpl::true_) const;
1073
1074   /**
1075    * INTERNAL ONLY
1076    *
1077    * We're receiving a type that does not have an associated MPI
1078    * datatype, so it must have been serialized then sent as
1079    * MPI_PACKED. We'll receive it and then deserialize.
1080    */
1081   template<typename T>
1082   request
1083   array_irecv_impl(int source, int tag, T* values, int n, mpl::false_) const;
1084
1085   // We're sending/receivig a vector with associated MPI datatype.
1086   // We need to send/recv the size and then the data and make sure
1087   // blocking and non blocking method agrees on the format.
1088   template<typename T, typename A>
1089   request irecv_vector(int source, int tag, std::vector<T,A>& values,
1090                        mpl::true_) const;
1091   template<typename T, class A>
1092   request isend_vector(int dest, int tag, const std::vector<T,A>& values,
1093                        mpl::true_) const;
1094   template<typename T, typename A>
1095   void send_vector(int dest, int tag, const std::vector<T,A>& value,
1096                    mpl::true_) const;
1097   template<typename T, typename A>
1098   status recv_vector(int source, int tag, std::vector<T,A>& value,
1099                      mpl::true_) const;
1100
1101   // We're sending/receivig a vector with no associated MPI datatype.
1102   // We need to send/recv it as an archive and make sure
1103   // blocking and non blocking method agrees on the format.
1104   template<typename T, typename A>
1105   request irecv_vector(int source, int tag, std::vector<T,A>& values,
1106                        mpl::false_) const;
1107   template<typename T, class A>
1108   request isend_vector(int dest, int tag, const std::vector<T,A>& values,
1109                        mpl::false_) const;
1110   template<typename T, typename A>
1111   void send_vector(int dest, int tag, const std::vector<T,A>& value,
1112                    mpl::false_) const;
1113   template<typename T, typename A>
1114   status recv_vector(int source, int tag, std::vector<T,A>& value,
1115                      mpl::false_) const;
1116
1117  protected:
1118   shared_ptr<MPI_Comm> comm_ptr;
1119 };
1120
1121 /**
1122  * @brief Determines whether two communicators are identical.
1123  *
1124  * Equivalent to calling @c MPI_Comm_compare and checking whether the
1125  * result is @c MPI_IDENT.
1126  *
1127  * @returns True when the two communicators refer to the same
1128  * underlying MPI communicator.
1129  */
1130 BOOST_MPI_DECL bool operator==(const communicator& comm1, const communicator& comm2);
1131
1132 /**
1133  * @brief Determines whether two communicators are different.
1134  *
1135  * @returns @c !(comm1 == comm2)
1136  */
1137 inline bool operator!=(const communicator& comm1, const communicator& comm2)
1138 {
1139   return !(comm1 == comm2);
1140 }
1141
1142 }} // boost::mpi
1143
1144 /************************************************************************
1145  * Implementation details                                               *
1146  ************************************************************************/
1147
1148 #include <boost/mpi/detail/request_handlers.hpp>
1149
1150 namespace boost { namespace mpi {
1151 /**
1152  * INTERNAL ONLY (using the same 'end' name might be considerd unfortunate
1153  */
1154 template<>
1155 BOOST_MPI_DECL void
1156 communicator::send<packed_oarchive>(int dest, int tag,
1157                                     const packed_oarchive& ar) const;
1158
1159 /**
1160  * INTERNAL ONLY
1161  */
1162 template<>
1163 BOOST_MPI_DECL void
1164 communicator::send<packed_skeleton_oarchive>
1165   (int dest, int tag, const packed_skeleton_oarchive& ar) const;
1166
1167 /**
1168  * INTERNAL ONLY
1169  */
1170 template<>
1171 BOOST_MPI_DECL void
1172 communicator::send<content>(int dest, int tag, const content& c) const;
1173
1174 /**
1175  * INTERNAL ONLY
1176  */
1177 template<>
1178 BOOST_MPI_DECL status
1179 communicator::recv<packed_iarchive>(int source, int tag,
1180                                     packed_iarchive& ar) const;
1181
1182 /**
1183  * INTERNAL ONLY
1184  */
1185 template<>
1186 BOOST_MPI_DECL status
1187 communicator::recv<packed_skeleton_iarchive>
1188   (int source, int tag, packed_skeleton_iarchive& ar) const;
1189
1190 /**
1191  * INTERNAL ONLY
1192  */
1193 template<>
1194 BOOST_MPI_DECL status
1195 communicator::recv<const content>(int source, int tag,
1196                                   const content& c) const;
1197
1198 /**
1199  * INTERNAL ONLY
1200  */
1201 template<>
1202 inline status
1203 communicator::recv<content>(int source, int tag,
1204                                   content& c) const
1205 {
1206   return recv<const content>(source,tag,c);
1207 }
1208
1209 /**
1210  * INTERNAL ONLY
1211  */
1212 template<>
1213 BOOST_MPI_DECL request
1214 communicator::isend<packed_oarchive>(int dest, int tag,
1215                                      const packed_oarchive& ar) const;
1216
1217 /**
1218  * INTERNAL ONLY
1219  */
1220 template<>
1221 BOOST_MPI_DECL request
1222 communicator::isend<packed_skeleton_oarchive>
1223   (int dest, int tag, const packed_skeleton_oarchive& ar) const;
1224
1225 /**
1226  * INTERNAL ONLY
1227  */
1228 template<>
1229 BOOST_MPI_DECL request
1230 communicator::isend<content>(int dest, int tag, const content& c) const;
1231
1232 /**
1233  * INTERNAL ONLY
1234  */
1235 template<>
1236 BOOST_MPI_DECL request
1237 communicator::irecv<packed_skeleton_iarchive>
1238   (int source, int tag, packed_skeleton_iarchive& ar) const;
1239
1240 /**
1241  * INTERNAL ONLY
1242  */
1243 template<>
1244 BOOST_MPI_DECL request
1245 communicator::irecv<const content>(int source, int tag,
1246                                    const content& c) const;
1247
1248 /**
1249  * INTERNAL ONLY
1250  */
1251 template<>
1252 inline request
1253 communicator::irecv<content>(int source, int tag,
1254                              content& c) const
1255 {
1256   return irecv<const content>(source, tag, c);
1257 }
1258
1259 // Count elements in a message
1260 template<typename T>
1261 inline optional<int> status::count() const
1262 {
1263   return count_impl<T>(is_mpi_datatype<T>());
1264 }
1265
1266 template<typename T>
1267 optional<int> status::count_impl(mpl::true_) const
1268 {
1269   if (m_count != -1)
1270     return m_count;
1271
1272   int return_value;
1273   BOOST_MPI_CHECK_RESULT(MPI_Get_count,
1274                          (&m_status, get_mpi_datatype<T>(T()), &return_value));
1275   if (return_value == MPI_UNDEFINED)
1276     return optional<int>();
1277   else
1278     /* Cache the result. */
1279     return m_count = return_value;
1280 }
1281
1282 template<typename T>
1283 inline optional<int> status::count_impl(mpl::false_) const
1284 {
1285   if (m_count == -1)
1286     return optional<int>();
1287   else
1288     return m_count;
1289 }
1290
1291 // We're sending a type that has an associated MPI datatype, so we
1292 // map directly to that datatype.
1293 template<typename T>
1294 void
1295 communicator::send_impl(int dest, int tag, const T& value, mpl::true_) const
1296 {
1297   // received by recv or trivial handler.
1298   BOOST_MPI_CHECK_RESULT(MPI_Send,
1299                          (const_cast<T*>(&value), 1, get_mpi_datatype<T>(value),
1300                           dest, tag, MPI_Comm(*this)));
1301 }
1302
1303 // We're sending a type that does not have an associated MPI
1304 // datatype, so it must be serialized then sent as MPI_PACKED data,
1305 // to be deserialized on the receiver side.
1306 template<typename T>
1307 void
1308 communicator::send_impl(int dest, int tag, const T& value, mpl::false_) const
1309 {
1310   packed_oarchive oa(*this);
1311   oa << value;
1312   send(dest, tag, oa);
1313 }
1314
1315 // Single-element receive may either send the element directly or
1316 // serialize it via a buffer.
1317 template<typename T>
1318 void communicator::send(int dest, int tag, const T& value) const
1319 {
1320   this->send_impl(dest, tag, value, is_mpi_datatype<T>());
1321 }
1322
1323 // We're sending an array of a type that has an associated MPI
1324 // datatype, so we map directly to that datatype.
1325 template<typename T>
1326 void
1327 communicator::array_send_impl(int dest, int tag, const T* values, int n,
1328                               mpl::true_) const
1329 {
1330   BOOST_MPI_CHECK_RESULT(MPI_Send,
1331                          (const_cast<T*>(values), n,
1332                           get_mpi_datatype<T>(*values),
1333                           dest, tag, MPI_Comm(*this)));
1334 }
1335
1336 // We're sending an array of a type that does not have an associated
1337 // MPI datatype, so it must be serialized then sent as MPI_PACKED
1338 // data, to be deserialized on the receiver side.
1339 template<typename T>
1340 void
1341 communicator::array_send_impl(int dest, int tag, const T* values, int n,
1342                               mpl::false_) const
1343 {
1344   packed_oarchive oa(*this);
1345   T const* v = values;
1346   while (v < values+n) {
1347     oa << *v++;
1348   }
1349   send(dest, tag, oa);
1350 }
1351
1352 template<typename T, typename A>
1353 void communicator::send_vector(int dest, int tag,
1354   const std::vector<T,A>& values, mpl::true_ primitive) const
1355 {
1356 #if defined(BOOST_MPI_USE_IMPROBE)
1357   array_send_impl(dest, tag, values.data(), values.size(), primitive);
1358 #else
1359   {
1360     // non blocking recv by legacy_dynamic_primitive_array_handler
1361     // blocking recv by recv_vector(source,tag,value,primitive)
1362     // send the vector size
1363     typename std::vector<T,A>::size_type size = values.size();
1364     send(dest, tag, size);
1365     // send the data
1366     this->array_send_impl(dest, tag, values.data(), size, primitive);
1367   }
1368 #endif
1369 }
1370
1371 template<typename T, typename A>
1372 void communicator::send_vector(int dest, int tag,
1373   const std::vector<T,A>& value, mpl::false_ primitive) const
1374 {
1375   this->send_impl(dest, tag, value, primitive);
1376 }
1377
1378 template<typename T, typename A>
1379 void communicator::send(int dest, int tag, const std::vector<T,A>& value) const
1380 {
1381   send_vector(dest, tag, value, is_mpi_datatype<T>());
1382 }
1383
1384 // Array send must send the elements directly
1385 template<typename T>
1386 void communicator::send(int dest, int tag, const T* values, int n) const
1387 {
1388   this->array_send_impl(dest, tag, values, n, is_mpi_datatype<T>());
1389 }
1390
1391 // We're receiving a type that has an associated MPI datatype, so we
1392 // map directly to that datatype.
1393 template<typename T>
1394 status communicator::recv_impl(int source, int tag, T& value, mpl::true_) const
1395 {
1396   status stat;
1397   BOOST_MPI_CHECK_RESULT(MPI_Recv,
1398                          (const_cast<T*>(&value), 1,
1399                           get_mpi_datatype<T>(value),
1400                           source, tag, MPI_Comm(*this), &stat.m_status));
1401   return stat;
1402 }
1403
1404 template<typename T>
1405 status
1406 communicator::recv_impl(int source, int tag, T& value, mpl::false_) const
1407 {
1408   // Receive the message
1409   packed_iarchive ia(*this);
1410   status stat = recv(source, tag, ia);
1411
1412   // Deserialize the data in the message
1413   ia >> value;
1414
1415   return stat;
1416 }
1417
1418 // Single-element receive may either receive the element directly or
1419 // deserialize it from a buffer.
1420 template<typename T>
1421 status communicator::recv(int source, int tag, T& value) const
1422 {
1423   return this->recv_impl(source, tag, value, is_mpi_datatype<T>());
1424 }
1425
1426 template<typename T>
1427 status
1428 communicator::array_recv_impl(int source, int tag, T* values, int n,
1429                               mpl::true_) const
1430 {
1431   status stat;
1432   BOOST_MPI_CHECK_RESULT(MPI_Recv,
1433                          (const_cast<T*>(values), n,
1434                           get_mpi_datatype<T>(*values),
1435                           source, tag, MPI_Comm(*this), &stat.m_status));
1436   return stat;
1437 }
1438
1439 template<typename T>
1440 status
1441 communicator::array_recv_impl(int source, int tag, T* values, int n,
1442                               mpl::false_) const
1443 {
1444   packed_iarchive ia(*this);
1445   status stat = recv(source, tag, ia);
1446   T* v = values;
1447   while (v != values+n) {
1448     ia >> *v++;
1449   }
1450   stat.m_count = n;
1451   return stat;
1452 }
1453
1454 template<typename T, typename A>
1455 status communicator::recv_vector(int source, int tag,
1456                                  std::vector<T,A>& values, mpl::true_ primitive) const
1457 {
1458 #if defined(BOOST_MPI_USE_IMPROBE)
1459   {
1460     MPI_Message msg;
1461     status stat;
1462     BOOST_MPI_CHECK_RESULT(MPI_Mprobe, (source,tag,*this,&msg,&stat.m_status));
1463     int count;
1464     BOOST_MPI_CHECK_RESULT(MPI_Get_count, (&stat.m_status,get_mpi_datatype<T>(),&count));
1465     values.resize(count);
1466     BOOST_MPI_CHECK_RESULT(MPI_Mrecv, (values.data(), count, get_mpi_datatype<T>(), &msg, &stat.m_status));
1467     return stat;
1468   }
1469 #else
1470   {
1471     // receive the vector size
1472     typename std::vector<T,A>::size_type size = 0;
1473     recv(source, tag, size);
1474     // size the vector
1475     values.resize(size);
1476     // receive the data
1477     return this->array_recv_impl(source, tag, values.data(), size, primitive);
1478   }
1479 #endif
1480 }
1481
1482 template<typename T, typename A>
1483 status communicator::recv_vector(int source, int tag,
1484   std::vector<T,A>& value, mpl::false_ false_type) const
1485 {
1486   return this->recv_impl(source, tag, value, false_type);
1487 }
1488
1489 template<typename T, typename A>
1490 status communicator::recv(int source, int tag, std::vector<T,A>& value) const
1491 {
1492   return recv_vector(source, tag, value, is_mpi_datatype<T>());
1493 }
1494
1495 // Array receive must receive the elements directly into a buffer.
1496 template<typename T>
1497 status communicator::recv(int source, int tag, T* values, int n) const
1498 {
1499   return this->array_recv_impl(source, tag, values, n, is_mpi_datatype<T>());
1500 }
1501
1502
1503 template<typename T>
1504 status communicator::sendrecv_impl(int dest, int stag, const T& sval, int src, int rtag, T& rval,
1505                                     mpl::true_) const
1506 {
1507   status stat;
1508   BOOST_MPI_CHECK_RESULT(MPI_Sendrecv,
1509                          (const_cast<T*>(&sval), 1,
1510                           get_mpi_datatype<T>(sval),
1511                           dest, stag,
1512                           &rval, 1,
1513                           get_mpi_datatype<T>(rval),
1514                           src, rtag,
1515                           MPI_Comm(*this), &stat.m_status));
1516   return stat;
1517 }
1518
1519 template<typename T>
1520 status communicator::sendrecv_impl(int dest, int stag, const T& sval, int src, int rtag, T& rval,
1521                                    mpl::false_) const
1522 {
1523   int const SEND = 0;
1524   int const RECV = 1;
1525   request srrequests[2];
1526   srrequests[SEND] = this->isend_impl(dest, stag, sval, mpl::false_());
1527   srrequests[RECV] = this->irecv_impl(src,  rtag, rval, mpl::false_());
1528   status srstatuses[2];
1529   wait_all(srrequests, srrequests + 2, srstatuses);
1530   return srstatuses[RECV];
1531 }
1532
1533 template<typename T>
1534 status communicator::sendrecv(int dest, int stag, const T& sval, int src, int rtag, T& rval) const
1535 {
1536   return this->sendrecv_impl(dest, stag, sval, src, rtag, rval, is_mpi_datatype<T>());
1537 }
1538
1539
1540 // We're sending a type that has an associated MPI datatype, so we
1541 // map directly to that datatype.
1542 template<typename T>
1543 request
1544 communicator::isend_impl(int dest, int tag, const T& value, mpl::true_) const
1545 {
1546   return request::make_trivial_send(*this, dest, tag, value);
1547 }
1548
1549 // We're sending a type that does not have an associated MPI
1550 // datatype, so it must be serialized then sent as MPI_PACKED data,
1551 // to be deserialized on the receiver side.
1552 template<typename T>
1553 request
1554 communicator::isend_impl(int dest, int tag, const T& value, mpl::false_) const
1555 {
1556   shared_ptr<packed_oarchive> archive(new packed_oarchive(*this));
1557   *archive << value;
1558   request result = isend(dest, tag, *archive);
1559   result.preserve(archive);
1560   return result;
1561 }
1562
1563 // Single-element receive may either send the element directly or
1564 // serialize it via a buffer.
1565 template<typename T>
1566 request communicator::isend(int dest, int tag, const T& value) const
1567 {
1568   return this->isend_impl(dest, tag, value, is_mpi_datatype<T>());
1569 }
1570
1571 template<typename T, class A>
1572 request communicator::isend(int dest, int tag, const std::vector<T,A>& values) const
1573 {
1574   return this->isend_vector(dest, tag, values, is_mpi_datatype<T>());
1575 }
1576
1577 template<typename T, class A>
1578 request
1579 communicator::isend_vector(int dest, int tag, const std::vector<T,A>& values,
1580                            mpl::true_ primitive) const
1581 {
1582   return request::make_dynamic_primitive_array_send(*this, dest, tag, values);
1583 }
1584
1585 template<typename T, class A>
1586 request
1587 communicator::isend_vector(int dest, int tag, const std::vector<T,A>& values,
1588                            mpl::false_ no) const
1589 {
1590   return this->isend_impl(dest, tag, values, no);
1591 }
1592
1593 template<typename T>
1594 request
1595 communicator::array_isend_impl(int dest, int tag, const T* values, int n,
1596                                mpl::true_) const
1597 {
1598   return request::make_trivial_send(*this, dest, tag, values, n);
1599 }
1600
1601 template<typename T>
1602 request
1603 communicator::array_isend_impl(int dest, int tag, const T* values, int n,
1604                                mpl::false_) const
1605 {
1606   shared_ptr<packed_oarchive> archive(new packed_oarchive(*this));
1607   T const* v = values;
1608   while (v < values+n) {
1609     *archive << *v++;
1610   }
1611   request result = isend(dest, tag, *archive);
1612   result.preserve(archive);
1613   return result;
1614 }
1615
1616
1617 // Array isend must send the elements directly
1618 template<typename T>
1619 request communicator::isend(int dest, int tag, const T* values, int n) const
1620 {
1621   return array_isend_impl(dest, tag, values, n, is_mpi_datatype<T>());
1622 }
1623
1624 // We're receiving a type that has an associated MPI datatype, so we
1625 // map directly to that datatype.
1626 template<typename T>
1627 request
1628 communicator::irecv_impl(int source, int tag, T& value, mpl::true_) const
1629 {
1630   return request::make_trivial_recv(*this, source, tag, value);
1631 }
1632
1633 template<typename T>
1634 request
1635 communicator::irecv_impl(int source, int tag, T& value, mpl::false_) const
1636 {
1637   return request::make_serialized(*this, source, tag, value);
1638 }
1639
1640 template<typename T>
1641 request
1642 communicator::irecv(int source, int tag, T& value) const
1643 {
1644   return this->irecv_impl(source, tag, value, is_mpi_datatype<T>());
1645 }
1646
1647 template<typename T>
1648 request
1649 communicator::array_irecv_impl(int source, int tag, T* values, int n,
1650                                mpl::true_) const
1651 {
1652   return request::make_trivial_recv(*this, source, tag, values, n);
1653 }
1654
1655 template<typename T>
1656 request
1657 communicator::array_irecv_impl(int source, int tag, T* values, int n,
1658                                mpl::false_) const
1659 {
1660   return request::make_serialized_array(*this, source, tag, values, n);
1661 }
1662
1663 template<typename T, class A>
1664 request
1665 communicator::irecv_vector(int source, int tag, std::vector<T,A>& values,
1666                            mpl::true_ primitive) const
1667 {
1668   return request::make_dynamic_primitive_array_recv(*this, source, tag, values);
1669 }
1670
1671 template<typename T, class A>
1672 request
1673 communicator::irecv_vector(int source, int tag, std::vector<T,A>& values,
1674                            mpl::false_ no) const
1675 {
1676   return irecv_impl(source, tag, values, no);
1677 }
1678
1679 template<typename T, typename A>
1680 request
1681 communicator::irecv(int source, int tag, std::vector<T,A>& values) const
1682 {
1683   return irecv_vector(source, tag, values, is_mpi_datatype<T>());
1684 }
1685
1686 // Array receive must receive the elements directly into a buffer.
1687 template<typename T>
1688 request communicator::irecv(int source, int tag, T* values, int n) const
1689 {
1690   return this->array_irecv_impl(source, tag, values, n, is_mpi_datatype<T>());
1691 }
1692
1693 } } // end namespace boost::mpi
1694
1695 // If the user has already included skeleton_and_content.hpp, include
1696 // the code to send/receive skeletons and content.
1697 #ifdef BOOST_MPI_SKELETON_AND_CONTENT_HPP
1698 #  include <boost/mpi/detail/communicator_sc.hpp>
1699 #endif
1700
1701 #ifdef BOOST_MSVC
1702 #  pragma warning(pop)
1703 #endif
1704
1705 #endif // BOOST_MPI_COMMUNICATOR_HPP