boost/mpi/datatype.hpp

   1 // Copyright 2004 The Trustees of Indiana University.
   2 // Copyright 2005 Matthias Troyer.
   3 // Copyright 2006 Douglas Gregor <doug.gregor -at- gmail.com>.
   4
   5 // Use, modification and distribution is subject to the Boost Software
   6 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
   7 // http://www.boost.org/LICENSE_1_0.txt)
   8
   9 //  Authors: Douglas Gregor
  10 //           Andrew Lumsdaine
  11 //           Matthias Troyer
  12
  13 /** @file datatype.hpp
  14  *
  15  *  This header provides the mapping from C++ types to MPI data types.
  16  */
  17 #ifndef BOOST_MPI_DATATYPE_HPP
  18 #define BOOST_MPI_DATATYPE_HPP
  19
  20 #include <boost/mpi/config.hpp>
  21 #include <boost/mpi/datatype_fwd.hpp>
  22 #include <mpi.h>
  23 #include <boost/config.hpp>
  24 #include <boost/mpl/bool.hpp>
  25 #include <boost/mpl/or.hpp>
  26 #include <boost/mpl/and.hpp>
  27 #include <boost/mpi/detail/mpi_datatype_cache.hpp>
  28 #include <boost/mpl/assert.hpp>
  29 #include <utility> // for std::pair
  30
  31 namespace boost { namespace mpi {
  32
  33 /**
  34  *  @brief Type trait that determines if there exists a built-in
  35  *  integer MPI data type for a given C++ type.
  36  *
  37  *  This ytpe trait determines when there is a direct mapping from a
  38  *  C++ type to an MPI data type that is classified as an integer data
  39  *  type. See @c is_mpi_builtin_datatype for general information about
  40  *  built-in MPI data types.
  41  */
  42 template<typename T>
  43 struct is_mpi_integer_datatype
  44   : public boost::mpl::false_ { };
  45
  46 /**
  47  *  @brief Type trait that determines if there exists a built-in
  48  *  floating point MPI data type for a given C++ type.
  49  *
  50  *  This ytpe trait determines when there is a direct mapping from a
  51  *  C++ type to an MPI data type that is classified as a floating
  52  *  point data type. See @c is_mpi_builtin_datatype for general
  53  *  information about built-in MPI data types.
  54  */
  55 template<typename T>
  56 struct is_mpi_floating_point_datatype
  57   : public boost::mpl::false_ { };
  58
  59 /**
  60  *  @brief Type trait that determines if there exists a built-in
  61  *  logical MPI data type for a given C++ type.
  62  *
  63  *  This ytpe trait determines when there is a direct mapping from a
  64  *  C++ type to an MPI data type that is classified as an logical data
  65  *  type. See @c is_mpi_builtin_datatype for general information about
  66  *  built-in MPI data types.
  67  */
  68 template<typename T>
  69 struct is_mpi_logical_datatype
  70   : public boost::mpl::false_ { };
  71
  72 /**
  73  *  @brief Type trait that determines if there exists a built-in
  74  *  complex MPI data type for a given C++ type.
  75  *
  76  *  This ytpe trait determines when there is a direct mapping from a
  77  *  C++ type to an MPI data type that is classified as an complex data
  78  *  type. See @c is_mpi_builtin_datatype for general information about
  79  *  built-in MPI data types.
  80  */
  81 template<typename T>
  82 struct is_mpi_complex_datatype
  83   : public boost::mpl::false_ { };
  84
  85 /**
  86  *  @brief Type trait that determines if there exists a built-in
  87  *  byte MPI data type for a given C++ type.
  88  *
  89  *  This ytpe trait determines when there is a direct mapping from a
  90  *  C++ type to an MPI data type that is classified as an byte data
  91  *  type. See @c is_mpi_builtin_datatype for general information about
  92  *  built-in MPI data types.
  93  */
  94 template<typename T>
  95 struct is_mpi_byte_datatype
  96   : public boost::mpl::false_ { };
  97
  98 /** @brief Type trait that determines if there exists a built-in MPI
  99  *  data type for a given C++ type.
 100  *
 101  *  This type trait determines when there is a direct mapping from a
 102  *  C++ type to an MPI type. For instance, the C++ @c int type maps
 103  *  directly to the MPI type @c MPI_INT. When there is a direct
 104  *  mapping from the type @c T to an MPI type, @c
 105  *  is_mpi_builtin_datatype will derive from @c mpl::true_ and the MPI
 106  *  data type will be accessible via @c get_mpi_datatype.
 107  *
 108  *  In general, users should not need to specialize this
 109  *  trait. However, if you have an additional C++ type that can map
 110  *  directly to only of MPI's built-in types, specialize either this
 111  *  trait or one of the traits corresponding to categories of MPI data
 112  *  types (@c is_mpi_integer_datatype, @c
 113  *  is_mpi_floating_point_datatype, @c is_mpi_logical_datatype, @c
 114  *  is_mpi_complex_datatype, or @c is_mpi_builtin_datatype). @c
 115  *  is_mpi_builtin_datatype derives @c mpl::true_ if any of the traits
 116  *  corresponding to MPI data type categories derived @c mpl::true_.
 117  */
 118 template<typename T>
 119 struct is_mpi_builtin_datatype
 120   : boost::mpl::or_<is_mpi_integer_datatype<T>,
 121                     is_mpi_floating_point_datatype<T>,
 122                     is_mpi_logical_datatype<T>,
 123                     is_mpi_complex_datatype<T>,
 124                     is_mpi_byte_datatype<T> >
 125 {
 126 };
 127
 128 /** @brief Type trait that determines if a C++ type can be mapped to
 129  *  an MPI data type.
 130  *
 131  *  This type trait determines if it is possible to build an MPI data
 132  *  type that represents a C++ data type. When this is the case, @c
 133  *  is_mpi_datatype derives @c mpl::true_ and the MPI data type will
 134  *  be accessible via @c get_mpi_datatype.
 135
 136  *  For any C++ type that maps to a built-in MPI data type (see @c
 137  *  is_mpi_builtin_datatype), @c is_mpi_data_type is trivially
 138  *  true. However, any POD ("Plain Old Data") type containing types
 139  *  that themselves can be represented by MPI data types can itself be
 140  *  represented as an MPI data type. For instance, a @c point3d class
 141  *  containing three @c double values can be represented as an MPI
 142  *  data type. To do so, first make the data type Serializable (using
 143  *  the Boost.Serialization library); then, specialize the @c
 144  *  is_mpi_datatype trait for the point type so that it will derive @c
 145  *  mpl::true_:
 146  *
 147  *    @code
 148  *    namespace boost { namespace mpi {
 149  *      template<> struct is_mpi_datatype<point>
 150  *        : public mpl::true_ { };
 151  *    } }
 152  *    @endcode
 153  */
 154 template<typename T>
 155 struct is_mpi_datatype
 156  : public is_mpi_builtin_datatype<T>
 157 {
 158 };
 159
 160 /** @brief Returns an MPI data type for a C++ type.
 161  *
 162  *  The function creates an MPI data type for the given object @c
 163  *  x. The first time it is called for a class @c T, the MPI data type
 164  *  is created and cached. Subsequent calls for objects of the same
 165  *  type @c T return the cached MPI data type.  The type @c T must
 166  *  allow creation of an MPI data type. That is, it must be
 167  *  Serializable and @c is_mpi_datatype<T> must derive @c mpl::true_.
 168  *
 169  *  For fundamental MPI types, a copy of the MPI data type of the MPI
 170  *  library is returned.
 171  *
 172  *  Note that since the data types are cached, the caller should never
 173  *  call @c MPI_Type_free() for the MPI data type returned by this
 174  *  call.
 175  *
 176  *  @param x for an optimized call, a constructed object of the type
 177  *  should be passed; otherwise, an object will be
 178  *  default-constructed.
 179  *
 180  *  @returns The MPI data type corresponding to type @c T.
 181  */
 182 template<typename T> MPI_Datatype get_mpi_datatype(const T& x)
 183 {
 184   BOOST_MPL_ASSERT((is_mpi_datatype<T>));
 185   return detail::mpi_datatype_cache().datatype(x);
 186 }
 187
 188 // Don't parse this part when we're generating Doxygen documentation.
 189 #ifndef BOOST_MPI_DOXYGEN
 190
 191 /// INTERNAL ONLY
 192 #define BOOST_MPI_DATATYPE(CppType, MPIType, Kind)                      \
 193 template<>                                                              \
 194 inline MPI_Datatype                                                     \
 195 get_mpi_datatype< CppType >(const CppType&) { return MPIType; }         \
 196                                                                         \
 197 template<>                                                              \
 198  struct BOOST_JOIN(is_mpi_,BOOST_JOIN(Kind,_datatype))< CppType >       \
 199 : boost::mpl::bool_<true>                                               \
 200 {}
 201
 202 /// INTERNAL ONLY
 203 BOOST_MPI_DATATYPE(packed, MPI_PACKED, builtin);
 204
 205 /// INTERNAL ONLY
 206 BOOST_MPI_DATATYPE(char, MPI_CHAR, builtin);
 207
 208 /// INTERNAL ONLY
 209 BOOST_MPI_DATATYPE(short, MPI_SHORT, integer);
 210
 211 /// INTERNAL ONLY
 212 BOOST_MPI_DATATYPE(int, MPI_INT, integer);
 213
 214 /// INTERNAL ONLY
 215 BOOST_MPI_DATATYPE(long, MPI_LONG, integer);
 216
 217 /// INTERNAL ONLY
 218 BOOST_MPI_DATATYPE(float, MPI_FLOAT, floating_point);
 219
 220 /// INTERNAL ONLY
 221 BOOST_MPI_DATATYPE(double, MPI_DOUBLE, floating_point);
 222
 223 /// INTERNAL ONLY
 224 BOOST_MPI_DATATYPE(long double, MPI_LONG_DOUBLE, floating_point);
 225
 226 /// INTERNAL ONLY
 227 BOOST_MPI_DATATYPE(unsigned char, MPI_UNSIGNED_CHAR, builtin);
 228
 229 /// INTERNAL ONLY
 230 BOOST_MPI_DATATYPE(unsigned short, MPI_UNSIGNED_SHORT, integer);
 231
 232 /// INTERNAL ONLY
 233 BOOST_MPI_DATATYPE(unsigned, MPI_UNSIGNED, integer);
 234
 235 /// INTERNAL ONLY
 236 BOOST_MPI_DATATYPE(unsigned long, MPI_UNSIGNED_LONG, integer);
 237
 238 /// INTERNAL ONLY
 239 #define BOOST_MPI_LIST2(A, B) A, B
 240 /// INTERNAL ONLY
 241 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(float, int)>, MPI_FLOAT_INT,
 242                    builtin);
 243 /// INTERNAL ONLY
 244 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(double, int)>, MPI_DOUBLE_INT,
 245                    builtin);
 246 /// INTERNAL ONLY
 247 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(long double, int)>,
 248                    MPI_LONG_DOUBLE_INT, builtin);
 249 /// INTERNAL ONLY
 250 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(long, int>), MPI_LONG_INT,
 251                    builtin);
 252 /// INTERNAL ONLY
 253 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(short, int>), MPI_SHORT_INT,
 254                    builtin);
 255 /// INTERNAL ONLY
 256 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(int, int>), MPI_2INT, builtin);
 257 #undef BOOST_MPI_LIST2
 258
 259 /// specialization of is_mpi_datatype for pairs
 260 template <class T, class U>
 261 struct is_mpi_datatype<std::pair<T,U> >
 262  : public mpl::and_<is_mpi_datatype<T>,is_mpi_datatype<U> >
 263 {
 264 };
 265
 266 // Define wchar_t specialization of is_mpi_datatype, if possible.
 267 #if !defined(BOOST_NO_INTRINSIC_WCHAR_T) && \
 268   (defined(MPI_WCHAR) || (defined(MPI_VERSION) && MPI_VERSION >= 2))
 269 BOOST_MPI_DATATYPE(wchar_t, MPI_WCHAR, builtin);
 270 #endif
 271
 272 // Define long long or __int64 specialization of is_mpi_datatype, if possible.
 273 #if defined(BOOST_HAS_LONG_LONG) && \
 274   (defined(MPI_LONG_LONG_INT) || (defined(MPI_VERSION) && MPI_VERSION >= 2))
 275 BOOST_MPI_DATATYPE(long long, MPI_LONG_LONG_INT, builtin);
 276 #elif defined(BOOST_HAS_MS_INT64) && \
 277   (defined(MPI_LONG_LONG_INT) || (defined(MPI_VERSION) && MPI_VERSION >= 2))
 278 BOOST_MPI_DATATYPE(__int64, MPI_LONG_LONG_INT, builtin);
 279 #endif
 280
 281 // Define unsigned long long or unsigned __int64 specialization of
 282 // is_mpi_datatype, if possible. We separate this from the check for
 283 // the (signed) long long/__int64 because some MPI implementations
 284 // (e.g., MPICH-MX) have MPI_LONG_LONG_INT but not
 285 // MPI_UNSIGNED_LONG_LONG.
 286 #if defined(BOOST_HAS_LONG_LONG) && \
 287   (defined(MPI_UNSIGNED_LONG_LONG) \
 288    || (defined(MPI_VERSION) && MPI_VERSION >= 2))
 289 BOOST_MPI_DATATYPE(unsigned long long, MPI_UNSIGNED_LONG_LONG, builtin);
 290 #elif defined(BOOST_HAS_MS_INT64) && \
 291   (defined(MPI_UNSIGNED_LONG_LONG) \
 292    || (defined(MPI_VERSION) && MPI_VERSION >= 2))
 293 BOOST_MPI_DATATYPE(unsigned __int64, MPI_UNSIGNED_LONG_LONG, builtin);
 294 #endif
 295
 296 // Define signed char specialization of is_mpi_datatype, if possible.
 297 #if defined(MPI_SIGNED_CHAR) || (defined(MPI_VERSION) && MPI_VERSION >= 2)
 298 BOOST_MPI_DATATYPE(signed char, MPI_SIGNED_CHAR, builtin);
 299 #endif
 300
 301 #endif // Doxygen
 302
 303 namespace detail {
 304   inline MPI_Datatype build_mpi_datatype_for_bool()
 305   {
 306     MPI_Datatype type;
 307     MPI_Type_contiguous(sizeof(bool), MPI_BYTE, &type);
 308     MPI_Type_commit(&type);
 309     return type;
 310   }
 311 }
 312
 313 /// Support for bool. There is no corresponding MPI_BOOL.
 314 /// INTERNAL ONLY
 315 template<>
 316 inline MPI_Datatype get_mpi_datatype<bool>(const bool&)
 317 {
 318   static MPI_Datatype type = detail::build_mpi_datatype_for_bool();
 319   return type;
 320 }
 321
 322 /// INTERNAL ONLY
 323 template<>
 324 struct is_mpi_datatype<bool>
 325   : boost::mpl::bool_<true>
 326 {};
 327
 328 } } // end namespace boost::mpi
 329
 330 // define a macro to make explicit designation of this more transparent
 331 #define BOOST_IS_MPI_DATATYPE(T)              \
 332 namespace boost {                             \
 333 namespace mpi {                               \
 334 template<>                                    \
 335 struct is_mpi_datatype< T > : mpl::true_ {};  \
 336 }}                                            \
 337 /**/
 338
 339
 340 #endif // BOOST_MPI_MPI_DATATYPE_HPP