Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

# Tools/MessageQueue/MessageQueue.h

Go to the documentation of this file.

    00001 /**
    00002 * @file MessageQueue.h
    00003 *
    00004 * Definition of class MessageQueue.
    00005 *
    00006 * Include this file if for declaring instances of MessageQueue.
    00007 *
    00008 * @author Martin Lötzsch
    00009 */
    00010
    00011 #ifndef __MessageQueue_h_
    00012 #define __MessageQueue_h_
    00013
    00014 #include "InMessage.h"
    00015 #include "OutMessage.h"
    00016
    00017 /**
    00018 * @class MessageQueue
    00019 *
    00020 * A queue for size varying, time stamped and type safe messages.
    00021 * It can be used to collect very different types of messages for exchange between different
    00022 * threads, processes or systems.
    00023 *
    00024 * @author Martin Lötzsch
    00025 *
    00026 * Usage:
    00027 * <pre>
    00028 * MessageQueue myQueue;
    00029 * myQueue.setSize(100000); // set the size of data that can be stored in the queue
    00030 * Image image1;
    00031 * myQueue.out.bin << image1; // write the binary message
    00032 * myQueue.out.finishMessage(idImage); // finish the message, set the type id of the message
    00033 * //
    00034 * // ... copy the queue between processes, systems
    00035 * //
    00036 * if (myQueue.in.getMessageID() == idImage) // check for the type of the next message
    00037 * {
    00038 *   Image image2;
    00039 *   myQueue.in.bin >> image2;  // read the image from the queue
    00040 * }
    00041 * </pre>
    00042 */
    00043 class MessageQueue
    00044 {
    00045 protected:
    00046   /** the system dependend message queue base which is responsible for the data storage */
    00047   MessageQueueBase queue;
    00048
    00049   friend class CRemoteCamToolBar;
    00050
    00051 public:
    00052   /** An interface for reading messages from the queue */
    00053   InMessage in;
    00054
    00055   /** An interface for writing messages to the queue */
    00056   OutMessage out;
    00057
    00058   /** Default constructor */
    00059   MessageQueue();
    00060
    00061   /**
    00062   * Sets the size of memory which is allocated for the queue.
    00063   * Ignored on the Win32 platform (dynamic allocation).
    00064   * @param size The maximum size of the queue in Bytes.
    00065   */
    00066   void setSize(int size);
    00067
    00068   /** Returns the size of memory which is needed to write the queue to a stream. */
    00069   int getStreamedSize();
    00070
    00071   /**
    00072   * Specifies a team color and a player number that is atached to every new
    00073   * message. If not set, Player::undefinedTeamColor and Player::undefinedPlayerNumber
    00074   * is used.
    00075   */
    00076   void setPlayerForNewMessages(const Player& player);
    00077
    00078   /**
    00079   * Calls a given MessageHandler for all messages of a kind in the queue. Note that the messages
    00080   * still remain in the queue and have to be removed manually with clear().
    00081   * @param id handle only messages with this MessageID
    00082   * @param handler a reference to a MessageHandler derivate
    00083   */
    00084   void handleSpecificMessages(MessageID id, MessageHandler& handler);
    00085
    00086   /**
    00087   * Calls a given MessageHandler for all messages in the queue. Note that the messages
    00088   * still remain in the queue and have to be removed manually with clear().
    00089   * @param handler a reference to a MessageHandler derivate
    00090   */
    00091   void handleAllMessages(MessageHandler& handler);
    00092
    00093   /**
    00094   * Copies all messages from this queue to another queue.
    00095   * @param other the destination queue.
    00096   */
    00097   void copyAllMessages(MessageQueue& other);
    00098
    00099   /**
    00100   * Moves all messages from this queue to another queue.
    00101   * @param other the destination queue.
    00102   */
    00103   void moveAllMessages(MessageQueue& other);
    00104
    00105   /** Deletes all older messages from the queue if a newer
    00106     * message of same type is already in the queue.
    00107     * This method should not be called during message handling. */
    00108   void removeRepetitions() { queue.removeRepetitions(); }
    00109
    00110   /** Removes all messages from the queue */
    00111   void clear();
    00112
    00113   /** Returns if the queue contains no messages */
    00114   bool isEmpty() const;
    00115
    00116 protected:
    00117   /**
    00118   * Copies a single message to another queue
    00119   * @param message The number of the message
    00120   * @param other The other queue.
    00121   */
    00122   void copyMessage(int message, MessageQueue& other);
    00123
    00124   /** Gives the stream operator access to protected members */
    00125   friend In& operator>>(In& stream, MessageQueue& messageQueue);
    00126
    00127   /** Gives the stream operator access to protected members */
    00128   friend Out& operator<<(Out& stream, const MessageQueue& messageQueue);
    00129 };
    00130
    00131 /**
    00132  * Streaming operator that reads a MessageQueue from a stream.
    00133  * @param stream The stream from which is read.
    00134  * @param messageQueue The MessageQueue object.
    00135  * @return The stream.
    00136  */
    00137 In& operator>>(In& stream,MessageQueue& messageQueue);
    00138
    00139
    00140 /**
    00141  * Streaming operator that writes a MessageQueue to a stream.
    00142  * @param stream The stream to write on.
    00143  * @param messageQueue The MessageQueue object.
    00144  * @return The stream.
    00145  */
    00146 Out& operator<<(Out& stream, const MessageQueue& messageQueue);
    00147
    00148 /**
    00149 * Streaming operator that writes a InMessage to another MessageQueue.
    00150 * @param message The InMessage to write.
    00151 * @param queue The MessageQueue object.
    00152 */
    00153 void operator >> (InMessage& message, MessageQueue& queue);
    00154
    00155 #endif //__MesssageQueue_h_
    00156