src/Message/Message.h

Go to the documentation of this file.

// -*- C++ -*-
/***************************************************************************
 *
 * The IPPL Framework
 * 
 *
 * Visit http://people.web.psi.ch/adelmann/ for more details
 *
 ***************************************************************************/

#ifndef MESSAGE_H
#define MESSAGE_H

/***************************************************************************
 * Message - contains a list of items that comprise a set of data to be
 * sent, or received from, another node in a parallel architecture.  A person
 * creates a Message object, loads it with data to be sent, and gives it
 * to a Communicate object.
 *
 * The message consists of N 'MsgItem' objects, which each contain some
 * data; data is added sequentially to a new message using the 'put'
 * routine, and extracted using the 'get' routine.  The messages are
 * retrieved in a FIFO fashion - you put in messages, and get them out
 * in the order in which they were put in.  You can access MsgItem's via
 * random access with the [] operator, but it is important
 * to actually remove the data using 'get' as this will properly deal with
 * copying data and freeing up memory (if necessary).
 *
 * Note on usage: A Message is primarily intended to be created once,
 * given to a Communicate instance to transmit to another node, and then
 * to be unpacked or otherwise read by the receiver.  A received message
 * may be forwarded to another node, but it cannot be combined with another
 * or used to initialize a copy of the Message.  This is due to the problems
 * of resolving who needs to free up the storage used for the Message elements.
 ***************************************************************************/

// include files
#include "Utility/Inform.h"
#include "Utility/Pstring.h"
#include "AppTypes/dcomplex.h"
#include <stddef.h>

#ifdef IPPL_STDSTL
#include <vector>
using std::vector;
#else
#include <vector.h>
#endif // IPPL_STDSTL

#ifdef IPPL_USE_STANDARD_HEADERS
#include <iostream>
using namespace std;
#else
#include <iostream.h>
#endif

#include <string.h>
#include <stdlib.h>

// forward declarations
class Communicate;
class Message;
ostream& operator<<(ostream& o, const Message& m);

// Macros
// simple template traits class to tell if a type is a built-in type
// or not.  The classes have an enum which is 1 if the type is build-in,
// 0 otherwise.  The default case is 0, but specialized to 1 for other types.
template <class T>
struct MessageTypeIntrinsic {
  enum { builtin = 0 };
  enum { pointer = 0 };
};

#define DEFINE_BUILTIN_TRAIT_CLASS(T)                           \
template <>                                                     \
struct MessageTypeIntrinsic<T> {                                \
  enum { builtin = 1 };                                         \
  enum { pointer = 0 };                                         \
};                                                              \
template <>                                                     \
struct MessageTypeIntrinsic<T *> {                              \
  enum { builtin = 1 };                                         \
  enum { pointer = 1 };                                         \
};                                                              \
template <int N>                                                \
struct MessageTypeIntrinsic<T[N]> {                             \
  enum { builtin = 1 };                                         \
  enum { pointer = 1 };                                         \
};

#define DEFINE_ALL_BUILTIN_TRAIT_CLASS(T)       \
DEFINE_BUILTIN_TRAIT_CLASS(T)                   \
DEFINE_BUILTIN_TRAIT_CLASS(const T)

DEFINE_ALL_BUILTIN_TRAIT_CLASS(bool)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(char)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(unsigned char)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(short)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(unsigned short)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(int)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(unsigned int)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(long)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(unsigned long)
#if defined(IPPL_LONGLONG)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(long long)
#endif
DEFINE_ALL_BUILTIN_TRAIT_CLASS(float)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(double)
DEFINE_ALL_BUILTIN_TRAIT_CLASS(dcomplex)
#if ( defined(IPPL_HAS_TEMPLATED_COMPLEX) && \
      !defined(IPPL_USE_SINGLE_PRECISION) )
DEFINE_ALL_BUILTIN_TRAIT_CLASS(fComplex)
#endif

// ada change fcomplex to fComples cmee name clash



// a class to put single items into a Message, which can be specialized
// to the case of built-in types and other types.

template <class T, bool builtin, bool pointer>
struct PutSingleItem { };

// specialization to a non-built-in type, which is never assumed to be a ptr
template <class T>
struct PutSingleItem<T, false, false> {
  // put a value into a message
  static Message& put(Message&, const T&);
  // get a value out of a message
  static Message& get(Message&, T&);
  // version of put using a pair of iterators
  static Message& put(Message&, T, T);
  // version of put using a list of indices and an iterator
  static Message& put(Message&, const vector<size_t>&, T);
  // get_iter uses an output iterator
  static Message& get_iter(Message&, T);
};

// specialization to a built-in type that is not a pointer
template <class T>
struct PutSingleItem<T, true, false> {
  // put a value into a message
  static Message& put(Message&, const T&);
  // get a value out of a message
  static Message& get(Message&, T&);
};

// specialization to a pointer to a built-in type. In this class, we
// know that 'T' is a pointer type.
template <class T>
struct PutSingleItem<T, true, true> {
  // put using a pair of pointers
  static Message& put(Message&, T, T);
  // get using a pointer
  static Message& get(Message&, T);
  // put using a list of indices and a pointer
  static Message& put(Message&, const vector<size_t>&, T);
  // get using an output iterator
  static Message& get_iter(Message&, T);
};


class Message {

public:
  // a class which stores a single message element.  This will either store
  // a reference to the data (if copy=false), make an internal copy (if
  // copy=true, and it is large enough), or put the data into an internal
  // fast buffer (the MsgItemBuf struct).
  class MsgItem {
  private:
    // a very simple struct for storing MsgItem data
    struct MsgItemBuf {
#if defined(IPPL_LONGLONG)
      unsigned long long d1, d2, d3, d4;
#else
      unsigned long d1, d2, d3, d4;
#endif
      MsgItemBuf() { }
      MsgItemBuf(const MsgItemBuf& m) : d1(m.d1),d2(m.d2),d3(m.d3),d4(m.d4) {}
      ~MsgItemBuf() { }
    };

  public:
    // default constructor
    MsgItem() : item(0), elements(0), bytesize(0), needDelete(false) { }

    // regular constructor, with data to store
    MsgItem(void *d, unsigned int elems, unsigned int totbytes,
            bool needcopy, bool needdel) : item(&defbuf), elements(elems),
      bytesize(totbytes), needDelete(needdel) {
        if (totbytes > 0 && d != 0) {
          if (needcopy) {
            if (totbytes <= sizeof(MsgItemBuf)) {
              // copy data into internal buffer
              needDelete = false;
            } else {
              // malloc and copy over data
              item = malloc(totbytes);
              needDelete = true;
            }
            memcpy(item, d, totbytes);
          } else {
            // we just store a reference, we do not copy
            item = d;
          }
        } else {
          // no data in message
          item = 0;
          elements = 0;
          needDelete = false;
        }
    }

    // copy constructor
    MsgItem(const MsgItem &m) : item(&defbuf), defbuf(m.defbuf),
        elements(m.elements), bytesize(m.bytesize), needDelete(m.needDelete) {
          // either we just copy the 'item' pointer, or we copy the default buf
          if (m.item != &(m.defbuf))
            item = m.item;
    }

    // destructor
    ~MsgItem() { }

    // return our total byte size, number of elements, and elem size
    unsigned int numBytes() const { return bytesize; }
    unsigned int numElems() const { return elements; }
    unsigned int elemSize() const { return (elements>0?bytesize/elements:0); }

    // will we need to delete our data?
    bool willNeedDelete() const { return (needDelete && item != 0); }

    // cancel the need to delete the data
    void cancelDelete() { needDelete = false; }
    
    // return our item pointer
    void *data() { return item; }

    // delete our data item
    void deleteData() {
      if (willNeedDelete())
        free(item);
    }

  private:
    // pointer to the item; must be newed/deleted, or pointing to defbuf
    void *item;

    // number of individual elements, and total storage size in bytes
    unsigned int elements, bytesize;

    // default storage space; used for speed
    MsgItemBuf defbuf;

    // do we need to delete this item storage?
    bool needDelete;
  };

public:
  //
  // constructors and destructors
  //

  // 'default' constructor: just make an empty message, optionally requesting
  // how many items we should preallocate space for
  Message(unsigned int numelems = 8)
    : numRemoved(0), comm(0), commdata(0), DoCopy(true), DoDelete(true) {
    MsgItemList.reserve(numelems);
  }

  // destructor: delete all items in this message, as if 'get' had been
  // called for all the items
  ~Message();

  //
  // global Message operations
  //

  // return number of items left in this message
  size_t size() const { return (MsgItemList.size() - numRemoved); }
  size_t removed() const { return numRemoved; }
  bool empty() const { return (size() == 0); }

  // returns a reference to the Nth MsgItem.  Note that 'n' refers
  // to the index from te first unremoved item, and that 'get' and 'remove'
  // will remove the top item.
  MsgItem& item(size_t n) { return MsgItemList[n + numRemoved]; }
  const MsgItem& item(size_t n) const {
    return MsgItemList[n+numRemoved];
  }

  // indicate that the next message item should be copied (t) or just
  // remembered via a pointer (f)
  Message& setCopy(const bool c) {
    DoCopy = c;
    return *this;
  }
  bool willCopy() const { return DoCopy; }

  // indicate that the next message item memory should be deleted by this
  // object when the Message is deleted (t)
  Message& setDelete(const bool c) {
    DoDelete = c;
    return *this;
  }
  bool willDelete() const { return DoDelete; }

  // clear the message; deletes all its items
  Message& clear();

  // return and remove the next item from this message ... if the item
  // does not exist, NULL is returned.  This is similar to get, except that 
  // just a void* pointer to the data is returned (instead of having the
  // data copied into given storage), and this data is DEFINITELY a malloced
  // block of data that the user must deallocate using 'free' (NOT delete).
  // Like 'get', after this is called, the top MsgItem is removed.
  // If you wish to just access the Nth item's item  pointer, use
  // item(N).item  .
  void *remove();

  // tell this Message to call the special function 'cleanupMessage' with
  // the provided pointer, in case the message is using buffer space
  // allocated by the Communicate object.  If no Communicate object has
  // been provided, nothing is done
  void useCommunicate(Communicate *c, void *d) {
    comm = c;
    commdata = d;
  }

  //
  // routines to get and put data out of/into the message.
  //

  // NOTES for 'put' routines:
  // For intrinsic scalar values, there is one argument: the scalar item.
  // For arrays, there are two arguments: the begining and (one-past-end)
  // pointers (i.e. like iterators, but restricted to pointers).
  // For any other arbitrary type, calling put will in turn call the method
  // 'putMessage' in the provided object.  'putMessage' can then call put
  // to put in the proper intrinsic-type objects.
  //
  // When putting in data, you can have the data copied over, or just have
  // a pointer stored.  If a pointer is stored (copy=F), you must also
  // specify whether this Message object should be responsible for deleting
  // the data (delstor=T), or should just leave the storage alone after the
  // data has been retrieved with get.  These flags are set by calling
  // 'setCopy' and 'setDelete' with the desired setting.  After an item
  // has been 'put', the are set back to the default values 'copy=true' and
  // 'delete=true'.  You can use them in this way:
  //      Message msg;
  //      msg.setCopy(false).setDelete(false).put(data);
  // copy and delstor are used to increase performance.  They
  // should be used in the following circumstances:
  //    a. Data to be sent/rec is in a location that will not change before the
  // msg is used, but should not be affected after the Message is deleted.
  // For this case, use copy=F, delstor=F.
  //    b. Data for a message has already had space allocated for it, and so
  // does not need to be copied.  Also, since the space has been allocated
  // already, it must be freed when the msg is sent.  For this case, use
  // copy=F, delstor=T.
  //    c. For data that is in a volatile location, it must be copied to new
  // storage, so use copy=T, and don't specify any value for delstor (it will
  // be ignored if copy=T).

  // general templated version of put
  // for an arbitrary type, call the function 'putMessage' with this
  // message so that it can put in data any way it wants.  That function
  // should return a reference to this message.
  // 'putMessage' should be defined as:
  //                   Message& putMessage(Message &);
  template <class T>
  Message& put(const T& val) {
    return PutSingleItem<T,
                         MessageTypeIntrinsic<T>::builtin,
                         MessageTypeIntrinsic<T>::pointer>::put(*this, val);
  }

  // specialized versions of put for character strings
  /*
  Message &put(char *d) {       // null-terminated string
    return putmsg((void *)d, sizeof(char), strlen(d) + 1);
  }
  */
  Message &put(const char *d) { // null-terminated string
    return putmsg((void *)d, sizeof(char), strlen(d) + 1);
  }
  // specialized version for string class
  Message& put(const string& s) {
    int len = s.length() + 1;
    put(len);
    put(s.c_str());
    return *this;
  }

  // general templated version of put for two iterators
  // Template put using a pair of iterators.  This version is called by
  // the public 'put' with two iterators after getting the proper type
  // of the data pointed to by the iterators
  template <class ForwardIterator>
  Message& put(ForwardIterator beg, ForwardIterator end) {
    return PutSingleItem<ForwardIterator,
                         MessageTypeIntrinsic<ForwardIterator>::builtin,
                         MessageTypeIntrinsic<ForwardIterator>::pointer>::put(
                           *this, beg, end);
  }

  // for using an indirection list
  // Template put using an indirection list.  This version is called by
  // the public 'put' with an indirection list and a RandomAccessIterator
  // after getting the proper type of the data pointed to by the iterator
  template <class RandomAccessIterator>
  Message& put(const vector<size_t>& indices,
               RandomAccessIterator beg) {
    return PutSingleItem<RandomAccessIterator,
      MessageTypeIntrinsic<RandomAccessIterator>::builtin,
      MessageTypeIntrinsic<RandomAccessIterator>::pointer>::put(*this, 
                                                                indices, beg);
  }

  // general put routine; called by other cases
  // arguments are the item, its element size (in bytes),
  // and how many items total to copy (if 0, this is a scalar).
  Message &putmsg(void *, int, int = 0);


  // general templated version of get, for a ref or a pointer
  // for an arbitrary type, call the function 'getMessage' with this
  // message so that it can get data any way it wants.  That function
  // should return a reference to this message.
  // 'getMessage' should be defined as:
  //                   Message& getMessage(Message &);
  // NOTE: the argument is a const ref, but will be cast to non-const,
  // to eliminate warning messages about anachronisms.
  // general templated version of get.
  template <class T>
  Message& get(const T& cval) {
    T& val = const_cast<T&>(cval);
    return PutSingleItem<T,
                         MessageTypeIntrinsic<T>::builtin,
                         MessageTypeIntrinsic<T>::pointer>::get(*this, val);
  }

  // specialized version for string class
  Message& get(const string& s) {
    string& ncs = const_cast<string&>(s);
    int len;
    get(len);
    char* cstring = new char[len];
    get(cstring);
    ncs = cstring;
    delete [] cstring;
    return *this;
  }

  // this version of get just removes the data without copying it
  Message &get() { return getmsg(0); }

  // an iterator-based version of get, which uses a general
  // iterator approach to copy the data out of the storage into
  // the space pointed to by the given iterator
  // Template get using a pair of iterators.  This version is called by
  // the public 'get' with two iterators after getting the proper type
  // of the data pointed to by the iterators
  template <class OutputIterator>
  Message& get_iter(OutputIterator o) {
    return PutSingleItem<OutputIterator,
      MessageTypeIntrinsic<OutputIterator>::builtin,
      MessageTypeIntrinsic<OutputIterator>::pointer>::get_iter(*this, o);
  }

  // general get routine; called by other cases
  // arguments are the location where to write the data, and the type
  // of the data.
  Message &getmsg(void *);

private:
  // MsgItem's that are in this message
  vector<MsgItem> MsgItemList;

  // number of elements that have been removed (via get or remove)
  size_t numRemoved;

  // should we copy the next added item?  if not, just store pointer
  bool DoCopy;

  // should we be responsible for deleting the next item?
  bool DoDelete;

  // a Communicate object which should be informed when this object is
  // deleted, and a comm-supplied object that it might need
  Communicate *comm;
  void *commdata;

  // delete the data in the top MsgItem, and remove that item from the top
  // (by incrementing numRemoved)
  void deleteMsgItem();
};


// General template for the put routine:
template<class T>
inline void putMessage(Message &m, const T &t) {
  m.put(t);
}

// for using a pair of iterators
template<class ForwardIterator>
inline void putMessage(Message &m, ForwardIterator beg, ForwardIterator end) {
  m.put(beg, end);
}

// for using an indirection list
template <class RandomAccessIterator>
inline void putMessage(Message &m, const vector<size_t> &v,
                       RandomAccessIterator r) {
  m.put(v, r);
}


// General template for the get routine:
template<class T>
inline void getMessage(Message &m, T &t) {
  m.get(t);
}

// this templated version of getMessage is for arbitrary pointers
template<class T>
inline void getMessage(Message &m, T *t) {
  m.get_iter(t);
}

// this templated version of getMessage is for arbitrary pointers
template<class T>
inline void getMessage(Message &m, T *t, T *) {
  m.get_iter(t);
}

// an iterator-based version of get, which uses a general
// iterator approach to copy the data out of the storage into
// the space pointed to by the given iterator
template<class OutputIterator>
void getMessage_iter(Message &m, OutputIterator o) {
  m.get_iter(o);
}


#if ( defined(IPPL_MPIXX) || defined(IPPL_PM) )
#define main mpi_main
extern "C" {
  int mpi_main(int, char**);
}
#endif // IPPL_MPIXX || IPPL_PM

#include "Message/Message.cpp"

#endif // MESSAGE_H

/***************************************************************************
 * $RCSfile: Message.h,v $   $Author: adelmann $
 * $Revision: 1.1.1.1 $   $Date: 2003/01/23 07:40:28 $
 * IPPL_VERSION_ID: $Id: Message.h,v 1.1.1.1 2003/01/23 07:40:28 adelmann Exp $ 
 ***************************************************************************/

---