boost/mpi/skeleton_and_content.hpp

   1 // (C) Copyright 2005 Matthias Troyer
   2 // (C) Copyright 2006 Douglas Gregor <doug.gregor -at gmail.com>
   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 //  Authors: Matthias Troyer
   9 //           Douglas Gregor
  10
  11 /** @file skeleton_and_content.hpp
  12  *
  13  *  This header provides facilities that allow the structure of data
  14  *  types (called the "skeleton") to be transmitted and received
  15  *  separately from the content stored in those data types. These
  16  *  facilities are useful when the data in a stable data structure
  17  *  (e.g., a mesh or a graph) will need to be transmitted
  18  *  repeatedly. In this case, transmitting the skeleton only once
  19  *  saves both communication effort (it need not be sent again) and
  20  *  local computation (serialization need only be performed once for
  21  *  the content).
  22  */
  23 #ifndef BOOST_MPI_SKELETON_AND_CONTENT_HPP
  24 #define BOOST_MPI_SKELETON_AND_CONTENT_HPP
  25
  26 #include <boost/mpi/config.hpp>
  27 #include <boost/archive/detail/auto_link_archive.hpp>
  28 #include <boost/mpi/packed_iarchive.hpp>
  29 #include <boost/mpi/packed_oarchive.hpp>
  30 #include <boost/mpi/detail/forward_skeleton_iarchive.hpp>
  31 #include <boost/mpi/detail/forward_skeleton_oarchive.hpp>
  32 #include <boost/mpi/detail/ignore_iprimitive.hpp>
  33 #include <boost/mpi/detail/ignore_oprimitive.hpp>
  34 #include <boost/shared_ptr.hpp>
  35
  36 namespace boost { namespace mpi {
  37
  38 /**
  39  *  @brief A proxy that requests that the skeleton of an object be
  40  *  transmitted.
  41  *
  42  *  The @c skeleton_proxy is a lightweight proxy object used to
  43  *  indicate that the skeleton of an object, not the object itself,
  44  *  should be transmitted. It can be used with the @c send and @c recv
  45  *  operations of communicators or the @c broadcast collective. When a
  46  *  @c skeleton_proxy is sent, Boost.MPI generates a description
  47  *  containing the structure of the stored object. When that skeleton
  48  *  is received, the receiving object is reshaped to match the
  49  *  structure. Once the skeleton of an object as been transmitted, its
  50  *  @c content can be transmitted separately (often several times)
  51  *  without changing the structure of the object.
  52  */
  53 template <class T>
  54 struct BOOST_MPI_DECL skeleton_proxy
  55 {
  56   /**
  57    *  Constructs a @c skeleton_proxy that references object @p x.
  58    *
  59    *  @param x the object whose structure will be transmitted or
  60    *  altered.
  61    */
  62   skeleton_proxy(T& x)
  63    : object(x)
  64   {}
  65
  66   T& object;
  67 };
  68
  69 /**
  70  *  @brief Create a skeleton proxy object.
  71  *
  72  *  This routine creates an instance of the skeleton_proxy class. It
  73  *  will typically be used when calling @c send, @c recv, or @c
  74  *  broadcast, to indicate that only the skeleton (structure) of an
  75  *  object should be transmitted and not its contents.
  76  *
  77  *  @param x the object whose structure will be transmitted.
  78  *
  79  *  @returns a skeleton_proxy object referencing @p x
  80  */
  81 template <class T>
  82 inline const skeleton_proxy<T> skeleton(T& x)
  83 {
  84   return skeleton_proxy<T>(x);
  85 }
  86
  87 namespace detail {
  88   /// @brief a class holding an MPI datatype
  89   /// INTERNAL ONLY
  90   /// the type is freed upon destruction
  91   class BOOST_MPI_DECL mpi_datatype_holder : public boost::noncopyable
  92   {
  93   public:
  94     mpi_datatype_holder()
  95      : is_committed(false)
  96     {}
  97
  98     mpi_datatype_holder(MPI_Datatype t, bool committed = true)
  99      : d(t)
 100      , is_committed(committed)
 101     {}
 102
 103     void commit()
 104     {
 105       BOOST_MPI_CHECK_RESULT(MPI_Type_commit,(&d));
 106       is_committed=true;
 107     }
 108
 109     MPI_Datatype get_mpi_datatype() const
 110     {
 111       return d;
 112     }
 113
 114     ~mpi_datatype_holder()
 115     {
 116       int finalized=0;
 117       BOOST_MPI_CHECK_RESULT(MPI_Finalized,(&finalized));
 118       if (!finalized && is_committed)
 119         BOOST_MPI_CHECK_RESULT(MPI_Type_free,(&d));
 120     }
 121
 122   private:
 123     MPI_Datatype d;
 124     bool is_committed;
 125   };
 126 } // end namespace detail
 127
 128 /** @brief A proxy object that transfers the content of an object
 129  *  without its structure.
 130  *
 131  *  The @c content class indicates that Boost.MPI should transmit or
 132  *  receive the content of an object, but without any information
 133  *  about the structure of the object. It is only meaningful to
 134  *  transmit the content of an object after the receiver has already
 135  *  received the skeleton for the same object.
 136  *
 137  *  Most users will not use @c content objects directly. Rather, they
 138  *  will invoke @c send, @c recv, or @c broadcast operations using @c
 139  *  get_content().
 140  */
 141 class BOOST_MPI_DECL content
 142 {
 143 public:
 144   /**
 145    *  Constructs an empty @c content object. This object will not be
 146    *  useful for any Boost.MPI operations until it is reassigned.
 147    */
 148   content() {}
 149
 150   /**
 151    *  This routine initializes the @c content object with an MPI data
 152    *  type that refers to the content of an object without its structure.
 153    *
 154    *  @param d the MPI data type referring to the content of the object.
 155    *
 156    *  @param committed @c true indicates that @c MPI_Type_commit has
 157    *  already been excuted for the data type @p d.
 158    */
 159   content(MPI_Datatype d, bool committed=true)
 160    : holder(new detail::mpi_datatype_holder(d,committed))
 161   {}
 162
 163   /**
 164    *  Replace the MPI data type referencing the content of an object.
 165    *
 166    *  @param d the new MPI data type referring to the content of the
 167    *  object.
 168    *
 169    *  @returns *this
 170    */
 171   const content& operator=(MPI_Datatype d)
 172   {
 173     holder.reset(new detail::mpi_datatype_holder(d));
 174     return *this;
 175   }
 176
 177   /**
 178    * Retrieve the MPI data type that refers to the content of the
 179    * object.
 180    *
 181    * @returns the MPI data type, which should only be transmitted or
 182    * received using @c MPI_BOTTOM as the address.
 183    */
 184   MPI_Datatype get_mpi_datatype() const
 185   {
 186     return holder->get_mpi_datatype();
 187   }
 188
 189   /**
 190    *  Commit the MPI data type referring to the content of the
 191    *  object.
 192    */
 193   void commit()
 194   {
 195     holder->commit();
 196   }
 197
 198 private:
 199   boost::shared_ptr<detail::mpi_datatype_holder> holder;
 200 };
 201
 202 /** @brief Returns the content of an object, suitable for transmission
 203  *   via Boost.MPI.
 204  *
 205  *  The function creates an absolute MPI datatype for the object,
 206  *  where all offsets are counted from the address 0 (a.k.a. @c
 207  *  MPI_BOTTOM) instead of the address @c &x of the object. This
 208  *  allows the creation of MPI data types for complex data structures
 209  *  containing pointers, such as linked lists or trees.
 210  *
 211  *  The disadvantage, compared to relative MPI data types is that for
 212  *  each object a new MPI data type has to be created.
 213  *
 214  *  The contents of an object can only be transmitted when the
 215  *  receiver already has an object with the same structure or shape as
 216  *  the sender. To accomplish this, first transmit the skeleton of the
 217  *  object using, e.g., @c skeleton() or @c skeleton_proxy.
 218  *
 219  *  The type @c T has to allow creation of an absolute MPI data type
 220  *  (content).
 221  *
 222  *  @param x the object for which the content will be transmitted.
 223  *
 224  *  @returns the content of the object @p x, which can be used for
 225  *  transmission via @c send, @c recv, or @c broadcast.
 226  */
 227 template <class T> const content get_content(const T& x);
 228
 229 /** @brief An archiver that reconstructs a data structure based on the
 230  *  binary skeleton stored in a buffer.
 231  *
 232  *  The @c packed_skeleton_iarchive class is an Archiver (as in the
 233  *  Boost.Serialization library) that can construct the the shape of a
 234  *  data structure based on a binary skeleton stored in a buffer. The
 235  *  @c packed_skeleton_iarchive is typically used by the receiver of a
 236  *  skeleton, to prepare a data structure that will eventually receive
 237  *  content separately.
 238  *
 239  *  Users will not generally need to use @c packed_skeleton_iarchive
 240  *  directly. Instead, use @c skeleton or @c get_skeleton.
 241  */
 242 class BOOST_MPI_DECL packed_skeleton_iarchive
 243   : public detail::ignore_iprimitive,
 244     public detail::forward_skeleton_iarchive<packed_skeleton_iarchive,packed_iarchive>
 245 {
 246 public:
 247   /**
 248    *  Construct a @c packed_skeleton_iarchive for the given
 249    *  communicator.
 250    *
 251    *  @param comm The communicator over which this archive will be
 252    *  transmitted.
 253    *
 254    *  @param flags Control the serialization of the skeleton. Refer to
 255    *  the Boost.Serialization documentation before changing the
 256    *  default flags.
 257    */
 258   packed_skeleton_iarchive(MPI_Comm const & comm,
 259                            unsigned int flags =  boost::archive::no_header)
 260          : detail::forward_skeleton_iarchive<packed_skeleton_iarchive,packed_iarchive>(skeleton_archive_)
 261          , skeleton_archive_(comm,flags)
 262         {}
 263
 264   /**
 265    *  Construct a @c packed_skeleton_iarchive that unpacks a skeleton
 266    *  from the given @p archive.
 267    *
 268    *  @param archive the archive from which the skeleton will be
 269    *  unpacked.
 270    *
 271    */
 272   explicit packed_skeleton_iarchive(packed_iarchive & archive)
 273          : detail::forward_skeleton_iarchive<packed_skeleton_iarchive,packed_iarchive>(archive)
 274          , skeleton_archive_(MPI_COMM_WORLD, boost::archive::no_header)
 275         {}
 276
 277   /**
 278    *  Retrieve the archive corresponding to this skeleton.
 279    */
 280   const packed_iarchive& get_skeleton() const
 281   {
 282     return this->implementation_archive;
 283   }
 284
 285   /**
 286    *  Retrieve the archive corresponding to this skeleton.
 287    */
 288   packed_iarchive& get_skeleton()
 289   {
 290     return this->implementation_archive;
 291   }
 292
 293 private:
 294   /// Store the actual archive that holds the structure, unless the
 295   /// user overrides this with their own archive.
 296   packed_iarchive skeleton_archive_;
 297 };
 298
 299 /** @brief An archiver that records the binary skeleton of a data
 300  * structure into a buffer.
 301  *
 302  *  The @c packed_skeleton_oarchive class is an Archiver (as in the
 303  *  Boost.Serialization library) that can record the shape of a data
 304  *  structure (called the "skeleton") into a binary representation
 305  *  stored in a buffer. The @c packed_skeleton_oarchive is typically
 306  *  used by the send of a skeleton, to pack the skeleton of a data
 307  *  structure for transmission separately from the content.
 308  *
 309  *  Users will not generally need to use @c packed_skeleton_oarchive
 310  *  directly. Instead, use @c skeleton or @c get_skeleton.
 311  */
 312 class BOOST_MPI_DECL packed_skeleton_oarchive
 313   : public detail::ignore_oprimitive,
 314     public detail::forward_skeleton_oarchive<packed_skeleton_oarchive,packed_oarchive>
 315 {
 316 public:
 317   /**
 318    *  Construct a @c packed_skeleton_oarchive for the given
 319    *  communicator.
 320    *
 321    *  @param comm The communicator over which this archive will be
 322    *  transmitted.
 323    *
 324    *  @param flags Control the serialization of the skeleton. Refer to
 325    *  the Boost.Serialization documentation before changing the
 326    *  default flags.
 327    */
 328   packed_skeleton_oarchive(MPI_Comm const & comm,
 329                            unsigned int flags =  boost::archive::no_header)
 330          : detail::forward_skeleton_oarchive<packed_skeleton_oarchive,packed_oarchive>(skeleton_archive_)
 331          , skeleton_archive_(comm,flags)
 332         {}
 333
 334   /**
 335    *  Construct a @c packed_skeleton_oarchive that packs a skeleton
 336    *  into the given @p archive.
 337    *
 338    *  @param archive the archive to which the skeleton will be packed.
 339    *
 340    */
 341   explicit packed_skeleton_oarchive(packed_oarchive & archive)
 342          : detail::forward_skeleton_oarchive<packed_skeleton_oarchive,packed_oarchive>(archive)
 343          , skeleton_archive_(MPI_COMM_WORLD, boost::archive::no_header)
 344         {}
 345
 346   /**
 347    *  Retrieve the archive corresponding to this skeleton.
 348    */
 349   const packed_oarchive& get_skeleton() const
 350   {
 351     return this->implementation_archive;
 352   }
 353
 354 private:
 355   /// Store the actual archive that holds the structure.
 356   packed_oarchive skeleton_archive_;
 357 };
 358
 359 namespace detail {
 360   typedef boost::mpi::detail::forward_skeleton_oarchive<boost::mpi::packed_skeleton_oarchive,boost::mpi::packed_oarchive> type1;
 361   typedef boost::mpi::detail::forward_skeleton_iarchive<boost::mpi::packed_skeleton_iarchive,boost::mpi::packed_iarchive> type2;
 362 }
 363
 364
 365 } } // end namespace boost::mpi
 366
 367 #include <boost/mpi/detail/content_oarchive.hpp>
 368
 369 // For any headers that have provided declarations based on forward
 370 // declarations of the contents of this header, include definitions
 371 // for those declarations. This means that the inclusion of
 372 // skeleton_and_content.hpp enables the use of skeleton/content
 373 // transmission throughout the library.
 374 #ifdef BOOST_MPI_BROADCAST_HPP
 375 #  include <boost/mpi/detail/broadcast_sc.hpp>
 376 #endif
 377
 378 #ifdef BOOST_MPI_COMMUNICATOR_HPP
 379 #  include <boost/mpi/detail/communicator_sc.hpp>
 380 #endif
 381
 382 // required by export
 383 BOOST_SERIALIZATION_REGISTER_ARCHIVE(boost::mpi::packed_skeleton_oarchive)
 384 BOOST_SERIALIZATION_REGISTER_ARCHIVE(boost::mpi::packed_skeleton_iarchive)
 385 BOOST_SERIALIZATION_REGISTER_ARCHIVE(boost::mpi::detail::type1)
 386 BOOST_SERIALIZATION_REGISTER_ARCHIVE(boost::mpi::detail::type2)
 387
 388 BOOST_SERIALIZATION_USE_ARRAY_OPTIMIZATION(boost::mpi::packed_skeleton_oarchive)
 389 BOOST_SERIALIZATION_USE_ARRAY_OPTIMIZATION(boost::mpi::packed_skeleton_iarchive)
 390
 391 #endif // BOOST_MPI_SKELETON_AND_CONTENT_HPP