boost/mpi/status.hpp

0001 // Copyright (C) 2006 Douglas Gregor <doug.gregor -at- gmail.com>.
0002
0003 // Use, modification and distribution is subject to the Boost Software
0004 // License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at
0005 // http://www.boost.org/LICENSE_1_0.txt)
0006
0007 /** @file status.hpp
0008  *
0009  *  This header defines the class @c status, which reports on the
0010  *  results of point-to-point communication.
0011  */
0012 #ifndef BOOST_MPI_STATUS_HPP
0013 #define BOOST_MPI_STATUS_HPP
0014
0015 #include <boost/mpi/config.hpp>
0016 #include <boost/mpi/datatype.hpp>
0017 #include <boost/optional.hpp>
0018 #include <boost/mpl/bool.hpp>
0019
0020 namespace boost { namespace mpi {
0021
0022 class request;
0023 class communicator;
0024
0025 /** @brief Contains information about a message that has been or can
0026  *  be received.
0027  *
0028  *  This structure contains status information about messages that
0029  *  have been received (with @c communicator::recv) or can be received
0030  *  (returned from @c communicator::probe or @c
0031  *  communicator::iprobe). It permits access to the source of the
0032  *  message, message tag, error code (rarely used), or the number of
0033  *  elements that have been transmitted.
0034  */
0035 class BOOST_MPI_DECL status
0036 {
0037  public:
0038   status() : m_count(-1) { }
0039
0040   status(MPI_Status const& s) : m_status(s), m_count(-1) {}
0041
0042   /**
0043    * Retrieve the source of the message.
0044    */
0045   int source() const { return m_status.MPI_SOURCE; }
0046
0047   /**
0048    * Retrieve the message tag.
0049    */
0050   int tag() const { return m_status.MPI_TAG; }
0051
0052   /**
0053    * Retrieve the error code.
0054    */
0055   int error() const { return m_status.MPI_ERROR; }
0056
0057   /**
0058    * Determine whether the communication associated with this object
0059    * has been successfully cancelled.
0060   */
0061   bool cancelled() const;
0062
0063   /**
0064    * Determines the number of elements of type @c T contained in the
0065    * message. The type @c T must have an associated data type, i.e.,
0066    * @c is_mpi_datatype<T> must derive @c mpl::true_. In cases where
0067    * the type @c T does not match the transmitted type, this routine
0068    * will return an empty @c optional<int>.
0069    *
0070    * @returns the number of @c T elements in the message, if it can be
0071    * determined.
0072    */
0073   template<typename T> optional<int> count() const { return count_impl<T>(is_mpi_datatype<T>()); }
0074
0075   /**
0076    * References the underlying @c MPI_Status
0077    */
0078   operator       MPI_Status&()       { return m_status; }
0079
0080   /**
0081    * References the underlying @c MPI_Status
0082    */
0083   operator const MPI_Status&() const { return m_status; }
0084
0085  private:
0086   /**
0087    * INTERNAL ONLY
0088    */
0089   template<typename T> optional<int> count_impl(mpl::true_) const;
0090
0091   /**
0092    * INTERNAL ONLY
0093    */
0094   template<typename T> optional<int> count_impl(mpl::false_) const;
0095
0096  public: // friend templates are not portable
0097
0098   /// INTERNAL ONLY
0099   mutable MPI_Status m_status;
0100   mutable int m_count;
0101
0102   friend class communicator;
0103   friend class request;
0104 };
0105
0106 template<typename T>
0107 inline optional<int> status::count_impl(mpl::true_) const
0108 {
0109   if (m_count != -1)
0110     return m_count;
0111
0112   int return_value;
0113   BOOST_MPI_CHECK_RESULT(MPI_Get_count,
0114                          (&m_status, get_mpi_datatype<T>(T()), &return_value));
0115   if (return_value == MPI_UNDEFINED)
0116     return optional<int>();
0117   else
0118     /* Cache the result. */
0119     return m_count = return_value;
0120 }
0121
0122 template<typename T>
0123 inline optional<int> status::count_impl(mpl::false_) const
0124 {
0125   if (m_count == -1)
0126     return optional<int>();
0127   else
0128     return m_count;
0129 }
0130
0131
0132 } } // end namespace boost::mpi
0133
0134 #endif // BOOST_MPI_STATUS_HPP