boost/mpi/datatype.hpp

0001 // Copyright 2004 The Trustees of Indiana University.
0002 // Copyright 2005 Matthias Troyer.
0003 // Copyright 2006 Douglas Gregor <doug.gregor -at- gmail.com>.
0004
0005 // Use, modification and distribution is subject to the Boost Software
0006 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0007 // http://www.boost.org/LICENSE_1_0.txt)
0008
0009 //  Authors: Douglas Gregor
0010 //           Andrew Lumsdaine
0011 //           Matthias Troyer
0012
0013 /** @file datatype.hpp
0014  *
0015  *  This header provides the mapping from C++ types to MPI data types.
0016  */
0017 #ifndef BOOST_MPI_DATATYPE_HPP
0018 #define BOOST_MPI_DATATYPE_HPP
0019
0020 #include <boost/mpi/config.hpp>
0021 #include <boost/mpi/datatype_fwd.hpp>
0022 #include <mpi.h>
0023 #include <boost/config.hpp>
0024 #include <boost/mpl/bool.hpp>
0025 #include <boost/mpl/or.hpp>
0026 #include <boost/mpl/and.hpp>
0027 #include <boost/mpi/detail/mpi_datatype_cache.hpp>
0028 #include <boost/mpl/assert.hpp>
0029 #include <boost/archive/basic_archive.hpp>
0030 #include <boost/serialization/library_version_type.hpp>
0031 #include <boost/serialization/item_version_type.hpp>
0032 #include <utility> // for std::pair
0033
0034 #if defined(__cplusplus) && (201103L <= __cplusplus)
0035 #include <array>
0036 #endif
0037
0038 namespace boost { namespace mpi {
0039
0040 /**
0041  *  @brief Type trait that determines if there exists a built-in
0042  *  integer MPI data type for a given C++ type.
0043  *
0044  *  This type trait determines when there is a direct mapping from a
0045  *  C++ type to an MPI data type that is classified as an integer data
0046  *  type. See @c is_mpi_builtin_datatype for general information about
0047  *  built-in MPI data types.
0048  */
0049 template<typename T>
0050 struct is_mpi_integer_datatype
0051   : public boost::mpl::false_ { };
0052
0053 /**
0054  *  @brief Type trait that determines if there exists a built-in
0055  *  floating point MPI data type for a given C++ type.
0056  *
0057  *  This type trait determines when there is a direct mapping from a
0058  *  C++ type to an MPI data type that is classified as a floating
0059  *  point data type. See @c is_mpi_builtin_datatype for general
0060  *  information about built-in MPI data types.
0061  */
0062 template<typename T>
0063 struct is_mpi_floating_point_datatype
0064   : public boost::mpl::false_ { };
0065
0066 /**
0067  *  @brief Type trait that determines if there exists a built-in
0068  *  logical MPI data type for a given C++ type.
0069  *
0070  *  This type trait determines when there is a direct mapping from a
0071  *  C++ type to an MPI data type that is classified as an logical data
0072  *  type. See @c is_mpi_builtin_datatype for general information about
0073  *  built-in MPI data types.
0074  */
0075 template<typename T>
0076 struct is_mpi_logical_datatype
0077   : public boost::mpl::false_ { };
0078
0079 /**
0080  *  @brief Type trait that determines if there exists a built-in
0081  *  complex MPI data type for a given C++ type.
0082  *
0083  *  This type trait determines when there is a direct mapping from a
0084  *  C++ type to an MPI data type that is classified as a complex data
0085  *  type. See @c is_mpi_builtin_datatype for general information about
0086  *  built-in MPI data types.
0087  */
0088 template<typename T>
0089 struct is_mpi_complex_datatype
0090   : public boost::mpl::false_ { };
0091
0092 /**
0093  *  @brief Type trait that determines if there exists a built-in
0094  *  byte MPI data type for a given C++ type.
0095  *
0096  *  This type trait determines when there is a direct mapping from a
0097  *  C++ type to an MPI data type that is classified as an byte data
0098  *  type. See @c is_mpi_builtin_datatype for general information about
0099  *  built-in MPI data types.
0100  */
0101 template<typename T>
0102 struct is_mpi_byte_datatype
0103   : public boost::mpl::false_ { };
0104
0105 /** @brief Type trait that determines if there exists a built-in MPI
0106  *  data type for a given C++ type.
0107  *
0108  *  This type trait determines when there is a direct mapping from a
0109  *  C++ type to an MPI type. For instance, the C++ @c int type maps
0110  *  directly to the MPI type @c MPI_INT. When there is a direct
0111  *  mapping from the type @c T to an MPI type, @c
0112  *  is_mpi_builtin_datatype will derive from @c mpl::true_ and the MPI
0113  *  data type will be accessible via @c get_mpi_datatype.
0114  *
0115  *  In general, users should not need to specialize this
0116  *  trait. However, if you have an additional C++ type that can map
0117  *  directly to only of MPI's built-in types, specialize either this
0118  *  trait or one of the traits corresponding to categories of MPI data
0119  *  types (@c is_mpi_integer_datatype, @c
0120  *  is_mpi_floating_point_datatype, @c is_mpi_logical_datatype, @c
0121  *  is_mpi_complex_datatype, or @c is_mpi_builtin_datatype). @c
0122  *  is_mpi_builtin_datatype derives @c mpl::true_ if any of the traits
0123  *  corresponding to MPI data type categories derived @c mpl::true_.
0124  */
0125 template<typename T>
0126 struct is_mpi_builtin_datatype
0127   : boost::mpl::or_<is_mpi_integer_datatype<T>,
0128                     is_mpi_floating_point_datatype<T>,
0129                     is_mpi_logical_datatype<T>,
0130                     is_mpi_complex_datatype<T>,
0131                     is_mpi_byte_datatype<T> >
0132 {
0133 };
0134
0135 /** @brief Type trait that determines if a C++ type can be mapped to
0136  *  an MPI data type.
0137  *
0138  *  This type trait determines if it is possible to build an MPI data
0139  *  type that represents a C++ data type. When this is the case, @c
0140  *  is_mpi_datatype derives @c mpl::true_ and the MPI data type will
0141  *  be accessible via @c get_mpi_datatype.
0142
0143  *  For any C++ type that maps to a built-in MPI data type (see @c
0144  *  is_mpi_builtin_datatype), @c is_mpi_datatype is trivially
0145  *  true. However, any POD ("Plain Old Data") type containing types
0146  *  that themselves can be represented by MPI data types can itself be
0147  *  represented as an MPI data type. For instance, a @c point3d class
0148  *  containing three @c double values can be represented as an MPI
0149  *  data type. To do so, first make the data type Serializable (using
0150  *  the Boost.Serialization library); then, specialize the @c
0151  *  is_mpi_datatype trait for the point type so that it will derive @c
0152  *  mpl::true_:
0153  *
0154  *    @code
0155  *    namespace boost { namespace mpi {
0156  *      template<> struct is_mpi_datatype<point>
0157  *        : public mpl::true_ { };
0158  *    } }
0159  *    @endcode
0160  */
0161 template<typename T>
0162 struct is_mpi_datatype
0163  : public is_mpi_builtin_datatype<T>
0164 {
0165 };
0166
0167 /** @brief Returns an MPI data type for a C++ type.
0168  *
0169  *  The function creates an MPI data type for the given object @c
0170  *  x. The first time it is called for a class @c T, the MPI data type
0171  *  is created and cached. Subsequent calls for objects of the same
0172  *  type @c T return the cached MPI data type.  The type @c T must
0173  *  allow creation of an MPI data type. That is, it must be
0174  *  Serializable and @c is_mpi_datatype<T> must derive @c mpl::true_.
0175  *
0176  *  For fundamental MPI types, a copy of the MPI data type of the MPI
0177  *  library is returned.
0178  *
0179  *  Note that since the data types are cached, the caller should never
0180  *  call @c MPI_Type_free() for the MPI data type returned by this
0181  *  call.
0182  *
0183  *  @param x for an optimized call, a constructed object of the type
0184  *  should be passed; otherwise, an object will be
0185  *  default-constructed.
0186  *
0187  *  @returns The MPI data type corresponding to type @c T.
0188  */
0189 template<typename T> MPI_Datatype get_mpi_datatype(const T& x)
0190 {
0191   BOOST_MPL_ASSERT((is_mpi_datatype<T>));
0192   return detail::mpi_datatype_cache().datatype(x);
0193 }
0194
0195 // Don't parse this part when we're generating Doxygen documentation.
0196 #ifndef BOOST_MPI_DOXYGEN
0197
0198 /// INTERNAL ONLY
0199 #define BOOST_MPI_DATATYPE(CppType, MPIType, Kind)                      \
0200 template<>                                                              \
0201 inline MPI_Datatype                                                     \
0202 get_mpi_datatype< CppType >(const CppType&) { return MPIType; }         \
0203                                                                         \
0204 template<>                                                              \
0205  struct BOOST_JOIN(is_mpi_,BOOST_JOIN(Kind,_datatype))< CppType >       \
0206 : boost::mpl::true_                                                     \
0207 {}
0208
0209 /// INTERNAL ONLY
0210 BOOST_MPI_DATATYPE(packed, MPI_PACKED, builtin);
0211
0212 /// INTERNAL ONLY
0213 BOOST_MPI_DATATYPE(char, MPI_CHAR, builtin);
0214
0215 /// INTERNAL ONLY
0216 BOOST_MPI_DATATYPE(short, MPI_SHORT, integer);
0217
0218 /// INTERNAL ONLY
0219 BOOST_MPI_DATATYPE(int, MPI_INT, integer);
0220
0221 /// INTERNAL ONLY
0222 BOOST_MPI_DATATYPE(long, MPI_LONG, integer);
0223
0224 /// INTERNAL ONLY
0225 BOOST_MPI_DATATYPE(float, MPI_FLOAT, floating_point);
0226
0227 /// INTERNAL ONLY
0228 BOOST_MPI_DATATYPE(double, MPI_DOUBLE, floating_point);
0229
0230 /// INTERNAL ONLY
0231 BOOST_MPI_DATATYPE(long double, MPI_LONG_DOUBLE, floating_point);
0232
0233 /// INTERNAL ONLY
0234 BOOST_MPI_DATATYPE(unsigned char, MPI_UNSIGNED_CHAR, builtin);
0235
0236 /// INTERNAL ONLY
0237 BOOST_MPI_DATATYPE(unsigned short, MPI_UNSIGNED_SHORT, integer);
0238
0239 /// INTERNAL ONLY
0240 BOOST_MPI_DATATYPE(unsigned, MPI_UNSIGNED, integer);
0241
0242 /// INTERNAL ONLY
0243 BOOST_MPI_DATATYPE(unsigned long, MPI_UNSIGNED_LONG, integer);
0244
0245 /// INTERNAL ONLY
0246 #define BOOST_MPI_LIST2(A, B) A, B
0247 /// INTERNAL ONLY
0248 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(float, int)>, MPI_FLOAT_INT,
0249                    builtin);
0250 /// INTERNAL ONLY
0251 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(double, int)>, MPI_DOUBLE_INT,
0252                    builtin);
0253 /// INTERNAL ONLY
0254 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(long double, int)>,
0255                    MPI_LONG_DOUBLE_INT, builtin);
0256 /// INTERNAL ONLY
0257 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(long, int>), MPI_LONG_INT,
0258                    builtin);
0259 /// INTERNAL ONLY
0260 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(short, int>), MPI_SHORT_INT,
0261                    builtin);
0262 /// INTERNAL ONLY
0263 BOOST_MPI_DATATYPE(std::pair<BOOST_MPI_LIST2(int, int>), MPI_2INT, builtin);
0264 #undef BOOST_MPI_LIST2
0265
0266 /// specialization of is_mpi_datatype for pairs
0267 template <class T, class U>
0268 struct is_mpi_datatype<std::pair<T,U> >
0269  : public mpl::and_<is_mpi_datatype<T>,is_mpi_datatype<U> >
0270 {
0271 };
0272
0273 /// specialization of is_mpi_datatype for arrays
0274 #if defined(__cplusplus) && (201103L <= __cplusplus)
0275 template<class T, std::size_t N>
0276 struct is_mpi_datatype<std::array<T, N> >
0277  : public is_mpi_datatype<T>
0278 {
0279 };
0280 #endif
0281
0282 // Define wchar_t specialization of is_mpi_datatype, if possible.
0283 #if !defined(BOOST_NO_INTRINSIC_WCHAR_T) && \
0284   (defined(MPI_WCHAR) || (BOOST_MPI_VERSION >= 2))
0285 BOOST_MPI_DATATYPE(wchar_t, MPI_WCHAR, builtin);
0286 #endif
0287
0288 // Define long long or __int64 specialization of is_mpi_datatype, if possible.
0289 #if defined(BOOST_HAS_LONG_LONG) && \
0290   (defined(MPI_LONG_LONG_INT) || (BOOST_MPI_VERSION >= 2))
0291 BOOST_MPI_DATATYPE(long long, MPI_LONG_LONG_INT, builtin);
0292 #elif defined(BOOST_HAS_MS_INT64) && \
0293   (defined(MPI_LONG_LONG_INT) || (BOOST_MPI_VERSION >= 2))
0294 BOOST_MPI_DATATYPE(__int64, MPI_LONG_LONG_INT, builtin);
0295 #endif
0296
0297 // Define unsigned long long or unsigned __int64 specialization of
0298 // is_mpi_datatype, if possible. We separate this from the check for
0299 // the (signed) long long/__int64 because some MPI implementations
0300 // (e.g., MPICH-MX) have MPI_LONG_LONG_INT but not
0301 // MPI_UNSIGNED_LONG_LONG.
0302 #if defined(BOOST_HAS_LONG_LONG) && \
0303   (defined(MPI_UNSIGNED_LONG_LONG) \
0304    || (BOOST_MPI_VERSION >= 2))
0305 BOOST_MPI_DATATYPE(unsigned long long, MPI_UNSIGNED_LONG_LONG, builtin);
0306 #elif defined(BOOST_HAS_MS_INT64) && \
0307   (defined(MPI_UNSIGNED_LONG_LONG) \
0308    || (BOOST_MPI_VERSION >= 2))
0309 BOOST_MPI_DATATYPE(unsigned __int64, MPI_UNSIGNED_LONG_LONG, builtin);
0310 #endif
0311
0312 // Define signed char specialization of is_mpi_datatype, if possible.
0313 #if defined(MPI_SIGNED_CHAR) || (BOOST_MPI_VERSION >= 2)
0314 BOOST_MPI_DATATYPE(signed char, MPI_SIGNED_CHAR, builtin);
0315 #endif
0316
0317
0318 #endif // Doxygen
0319
0320 namespace detail {
0321   inline MPI_Datatype build_mpi_datatype_for_bool()
0322   {
0323     // this is explicitly freed in mpi_datatype_map::clear
0324     MPI_Datatype type;
0325     MPI_Type_contiguous(sizeof(bool), MPI_BYTE, &type);
0326     MPI_Type_commit(&type);
0327     return type;
0328   }
0329 }
0330
0331 /// Support for bool. There is no corresponding MPI_BOOL.
0332 /// INTERNAL ONLY
0333 template<>
0334 inline MPI_Datatype get_mpi_datatype<bool>(const bool&)
0335 {
0336   static MPI_Datatype type = detail::build_mpi_datatype_for_bool();
0337   return type;
0338 }
0339
0340 /// INTERNAL ONLY
0341 template<>
0342 struct is_mpi_datatype<bool>
0343   : boost::mpl::bool_<true>
0344 {};
0345
0346
0347 #ifndef BOOST_MPI_DOXYGEN
0348 // direct support for special primitive data types of the serialization library
0349 BOOST_MPI_DATATYPE(boost::serialization::library_version_type, get_mpi_datatype(uint_least16_t()), integer);
0350 BOOST_MPI_DATATYPE(boost::archive::version_type, get_mpi_datatype(uint_least8_t()), integer);
0351 BOOST_MPI_DATATYPE(boost::archive::class_id_type, get_mpi_datatype(int_least16_t()), integer);
0352 BOOST_MPI_DATATYPE(boost::archive::class_id_reference_type, get_mpi_datatype(int_least16_t()), integer);
0353 BOOST_MPI_DATATYPE(boost::archive::class_id_optional_type, get_mpi_datatype(int_least16_t()), integer);
0354 BOOST_MPI_DATATYPE(boost::archive::object_id_type, get_mpi_datatype(uint_least32_t()), integer);
0355 BOOST_MPI_DATATYPE(boost::archive::object_reference_type, get_mpi_datatype(uint_least32_t()), integer);
0356 BOOST_MPI_DATATYPE(boost::archive::tracking_type, get_mpi_datatype(bool()), builtin);
0357 BOOST_MPI_DATATYPE(boost::serialization::collection_size_type, get_mpi_datatype(std::size_t()), integer);
0358 BOOST_MPI_DATATYPE(boost::serialization::item_version_type, get_mpi_datatype(uint_least8_t()), integer);
0359 #endif // Doxygen
0360
0361
0362 } } // end namespace boost::mpi
0363
0364 // direct support for special primitive data types of the serialization library
0365 // in the case of homogeneous systems
0366 // define a macro to make explicit designation of this more transparent
0367 #define BOOST_IS_MPI_DATATYPE(T)              \
0368 namespace boost {                             \
0369 namespace mpi {                               \
0370 template<>                                    \
0371 struct is_mpi_datatype< T > : mpl::true_ {};  \
0372 }}                                            \
0373 /**/
0374
0375
0376 #endif // BOOST_MPI_MPI_DATATYPE_HPP