// @HEADER // *********************************************************************** // // Teuchos: Common Tools Package // Copyright (2004) Sandia Corporation // // Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive // license for use of this work by or on behalf of the U.S. Government. // // This library is free software; you can redistribute it and/or modify // it under the terms of the GNU Lesser General Public License as // published by the Free Software Foundation; either version 2.1 of the // License, or (at your option) any later version. // // This library is distributed in the hope that it will be useful, but // WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU // Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public // License along with this library; if not, write to the Free Software // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 // USA // Questions? Contact Michael A. Heroux (maherou@sandia.gov) // // *********************************************************************** // @HEADER #ifndef TEUCHOS_COMM_HPP #define TEUCHOS_COMM_HPP #include "Teuchos_ReductionOp.hpp" namespace Teuchos { /** \brief Abstract interface class for a basic communication channel between * one or more processes. * * This interface is templated on the ordinal type but only deals with buffers * of untyped data represented as arrays char type. All reduction * operations that are initiated by the concreate communicator object are * performed by user-defined ReductOpBase objects. It is the * responsibility of the ReductOpBase object to know what the currect * data type is, to perform casts or serializations/unserializations to and * from char[] buffers, and to know how to reduce the objects * correctly. It is strictly up to the client to correctly convert data types * to char[] arrays but there is a great deal of helper code to make * this easy and safe. * * ToDo: Finish documentation! */ template class Comm : virtual public Describable { public: //! @name Query functions //@{ /** \brief Returns the rank of this process. * * Postconditions: */ virtual int getRank() const = 0; /** \brief Returns the number of processes that make up this communicator. * * Postconditions: */ virtual int getSize() const = 0; //@} //! @name Collective Operations //@{ /** \brief Pause every process in *this communicator until all the * processes reach this point. */ virtual void barrier() const = 0; /** \brief Broadcast values from the root process to the slave processes. * * \param rootRank * [in] The rank of the root process. * \param count * [in] The number of bytes in buffer[]. * \param buffer * [in/out] Array (length bytes) of packed data. Must be set on input * on the root processes with rank root. On output, each processs, * including the root process contains the data. * * Preconditions: */ virtual void broadcast( const int rootRank, const Ordinal bytes, char buffer[] ) const = 0; /** \brief Gather values from each process to collect on all processes. * * \param sendBytes * [in] Number of entires in sendBuffer[] on input. * \param sendBuffer * [in] Array (length sendBytes) of data being sent from each process. * \param recvBytes * [in] Number of entires in recvBuffer[] which must be * equal to sendBytes*this->getSize(). This field is just here * for debug checking. * \param recvBuffer * [out] Array (length recvBytes) of all of the entires * sent from each processes. Specifically, recvBuffer[sendBytes*j+i], * for j=0...this->getSize()-1 and i=0...sendBytes-1, * is the entry sendBuffer[i] from process with rank j. * * Preconditions: */ virtual void gatherAll( const Ordinal sendBytes, const char sendBuffer[] ,const Ordinal recvBytes, char recvBuffer[] ) const = 0; /** \brief Global reduction. * * \param reductOp * [in] The user-defined reduction operation * \param bytes * [in] The length of the buffers sendBuffer[] and globalReducts[]. * \param sendBuffer * [in] Array (length bytes) of the data contributed from each process. * \param globalReducts * [out] Array (length bytes) of the global reduction from each process. */ virtual void reduceAll( const ValueTypeReductionOp &reductOp ,const Ordinal bytes, const char sendBuffer[], char globalReducts[] ) const = 0; /** \brief Global reduction combined with a scatter. * * \param reductOp * [in] The user-defined reduction operation. * \param sendBytes * [in] The number of entires in sendBuffer[]. This must be the same * in each process. * \param sendBuffer * [in] Array (length sendBytes) of the data contributed from each process. * \param recvCounts * [in] Array (length this->getSize()) which gives the number of element * blocks of block size blockSize from the global reduction that will be * recieved in each process. * \param blockSize * [in] Gives the block size for interpreting recvCount * \param myGlobalReducts * [out] Array (length blockSize*recvBytes[rank]) of the global reductions gathered * in this process. * * Preconditions: */ virtual void reduceAllAndScatter( const ValueTypeReductionOp &reductOp ,const Ordinal sendBytes, const char sendBuffer[] ,const Ordinal recvCounts[], const Ordinal blockSize, char myGlobalReducts[] ) const = 0; /** \brief Scan reduction. * * \param reductOp * [in] The user-defined reduction operation * \param bytes * [in] The length of the buffers sendBuffer[] and scanReducts[]. * \param sendBuffer * [in] Array (length bytes) of the data contributed from each process. * \param scanReducts * [out] Array (length bytes) of the reduction up to and including * this process. */ virtual void scan( const ValueTypeReductionOp &reductOp ,const Ordinal bytes, const char sendBuffer[], char scanReducts[] ) const = 0; //! @name Point-to-Point Operations //@{ /** \brief Blocking send of data from this process to another process. * * \param bytes * [in] The number of bytes of data being passed between processes. * \param sendBuffer * [in] Array (length bytes) of data being sent from this process. * This buffer can be immediately destroyed or reused as soon as the function * exits (that is why this function is "blocking"). * \param destRank * [in] The rank of the process to recieve the data. * * Preconditions:
    *
  • 0 <= destRank && destRank < this->getSize() *
  • destRank != this->getRank() *
*/ virtual void send( const Ordinal bytes, const char sendBuffer[], const int destRank ) const = 0; /** \brief Blocking receive of data from this process to another process. * * \param sourceRank * [in] The rank of the process to recieve the data from. If sourceRank < 0 then * data will be recieved from any process. * \param bytes * [in] The number of bytes of data being passed between processes. * \param recvBuffer * [out] Array (length bytes) of data being received from this process. * This buffer can be immediately used to access the data as soon as the function * exits (that is why this function is "blocking"). * * Preconditions:
    *
  • [sourceRank >= 0] sourceRank < this->getSize() *
  • sourceRank != this->getRank() *
* * \return Returns the senders rank. */ virtual int receive( const int sourceRank, const Ordinal bytes, char recvBuffer[] ) const = 0; //@} }; // class Comm } // namespace Teuchos #endif // TEUCHOS_COMM_HPP