boost/mpi/request.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 request.hpp
0008  *
0009  *  This header defines the class @c request, which contains a request
0010  *  for non-blocking communication.
0011  */
0012 #ifndef BOOST_MPI_REQUEST_HPP
0013 #define BOOST_MPI_REQUEST_HPP
0014
0015 #include <boost/mpi/config.hpp>
0016 #include <boost/mpi/status.hpp>
0017 #include <boost/optional.hpp>
0018 #include <boost/shared_ptr.hpp>
0019 #include <boost/mpi/packed_iarchive.hpp>
0020
0021 namespace boost { namespace mpi {
0022
0023 class status;
0024 class communicator;
0025
0026 /**
0027  *  @brief A request for a non-blocking send or receive.
0028  *
0029  *  This structure contains information about a non-blocking send or
0030  *  receive and will be returned from @c isend or @c irecv,
0031  *  respectively.
0032  */
0033 class BOOST_MPI_DECL request
0034 {
0035  public:
0036   /**
0037    *  Constructs a NULL request.
0038    */
0039   request();
0040
0041   /**
0042    * Send a known number of primitive objects in one MPI request.
0043    */
0044   template<typename T>
0045   static request make_trivial_send(communicator const& comm, int dest, int tag, T const& value);
0046   template<typename T>
0047   static request make_trivial_send(communicator const& comm, int dest, int tag, T const* values, int n);
0048   static request make_packed_send(communicator const& comm, int dest, int tag, void const* values, std::size_t n);
0049
0050   static request make_bottom_send(communicator const& comm, int dest, int tag, MPI_Datatype tp);
0051   static request make_empty_send(communicator const& comm, int dest, int tag);
0052   /**
0053    * Receive a known number of primitive objects in one MPI request.
0054    */
0055   template<typename T>
0056   static request make_trivial_recv(communicator const& comm, int dest, int tag, T& value);
0057   template<typename T>
0058   static request make_trivial_recv(communicator const& comm, int dest, int tag, T* values, int n);
0059
0060   static request make_bottom_recv(communicator const& comm, int dest, int tag, MPI_Datatype tp);
0061   static request make_empty_recv(communicator const& comm, int dest, int tag);
0062   /**
0063    * Construct request for simple data of unknown size.
0064    */
0065   static request make_dynamic();
0066   /**
0067    *  Constructs request for serialized data.
0068    */
0069   template<typename T>
0070   static request make_serialized(communicator const& comm, int source, int tag, T& value);
0071   /**
0072    *  Constructs request for array of complex data.
0073    */
0074   template<typename T>
0075   static request make_serialized_array(communicator const& comm, int source, int tag, T* values, int n);
0076   /**
0077    *  Request to recv array of primitive data.
0078    */
0079   template<typename T, class A>
0080   static request
0081   make_dynamic_primitive_array_recv(communicator const& comm, int source, int tag,
0082                                     std::vector<T,A>& values);
0083   /**
0084    *  Request to send array of primitive data.
0085    */
0086   template<typename T, class A>
0087   static request
0088   make_dynamic_primitive_array_send(communicator const& comm, int source, int tag,
0089                                     std::vector<T,A> const& values);
0090   /**
0091    *  Wait until the communication associated with this request has
0092    *  completed, then return a @c status object describing the
0093    *  communication.
0094    */
0095   status wait() { return m_handler ? m_handler->wait() : status(); }
0096
0097   /**
0098    *  Determine whether the communication associated with this request
0099    *  has completed successfully. If so, returns the @c status object
0100    *  describing the communication. Otherwise, returns an empty @c
0101    *  optional<> to indicate that the communication has not completed
0102    *  yet. Note that once @c test() returns a @c status object, the
0103    *  request has completed and @c wait() should not be called.
0104    */
0105   optional<status> test() { return active() ? m_handler->test() : optional<status>(); }
0106
0107   /**
0108    *  Cancel a pending communication, assuming it has not already been
0109    *  completed.
0110    */
0111   void cancel() { if (m_handler) { m_handler->cancel(); } m_preserved.reset(); }
0112
0113   /**
0114    * The trivial MPI requet implenting this request, provided it's trivial.
0115    * Probably irrelevant to most users.
0116    */
0117   optional<MPI_Request&> trivial() { return (m_handler
0118                          ? m_handler->trivial()
0119                          : optional<MPI_Request&>()); }
0120
0121   /**
0122    * Is this request potentialy pending ?
0123    */
0124   bool active() const { return bool(m_handler) && m_handler->active(); }
0125
0126   // Some data might need protection while the reqest is processed.
0127   void preserve(boost::shared_ptr<void> d);
0128
0129   class handler {
0130   public:
0131     virtual BOOST_MPI_DECL ~handler() = 0;
0132     virtual status wait() = 0;
0133     virtual optional<status> test() = 0;
0134     virtual void cancel() = 0;
0135
0136     virtual bool active() const = 0;
0137     virtual optional<MPI_Request&> trivial() = 0;
0138   };
0139
0140  private:
0141
0142   request(handler *h) : m_handler(h) {};
0143
0144   // specific implementations
0145   class legacy_handler;
0146   class trivial_handler;
0147   class dynamic_handler;
0148   template<typename T> class legacy_serialized_handler;
0149   template<typename T> class legacy_serialized_array_handler;
0150   template<typename T, class A> class legacy_dynamic_primitive_array_handler;
0151 #if BOOST_MPI_VERSION >= 3
0152   template<class Data> class probe_handler;
0153 #endif
0154  private:
0155   shared_ptr<handler> m_handler;
0156   shared_ptr<void>    m_preserved;
0157 };
0158
0159 } } // end namespace boost::mpi
0160
0161 #endif // BOOST_MPI_REQUEST_HPP