1/* 2 * Copyright 2007, Haiku, Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * Niels Sascha Reedijk, niels.reedijk@gmail.com 7 * 8 * Corresponds to: 9 * /trunk/headers/os/app/MessageQueue.h rev 19956 10 * /trunk/src/kits/app/MessageQueue.cpp rev 19956 11 */ 12 13/*! 14 \file MessageQueue.h 15 \ingroup app 16 \ingroup libbe 17 \brief Provides the BMessageQueue class. 18*/ 19 20 21/*! 22 \class BMessageQueue 23 \ingroup app 24 \ingroup libbe 25 \brief A container that maintains a queue of messages. 26 27 This class is used by BLooper to maintain a queue of messages that need to 28 be processed. This class has been designed as a first in, first out 29 container. 30 31 The default message handling of a BLooper probably suffices for most uses, 32 but if you want more control, you can perform operations using the methods 33 of this class. Use BLooper::MessageQueue() to retrieve the specific 34 BMessageQueue instance. 35 36 Note that you are encouraged to make sure that whichever operation you 37 perform, that you only do this after the object has been locked (see 38 Lock()). The most important method, NextMessage() will fail if you have not 39 complied with this requirement. 40*/ 41 42 43/*! 44 \fn BMessageQueue::BMessageQueue() 45 \brief Constructs an empty message queue. 46*/ 47 48 49/*! 50 \fn BMessageQueue::~BMessageQueue() 51 \brief Destruct the BMessageQueue. It iterates over any messages left on 52 the queue and deletes them. 53 54 The implementation is careful not to release the lock when the 55 BMessageQueue is deconstructed. If the lock is released, it is 56 possible another thread will start an AddMessage() operation before 57 the BLocker is deleted. The safe thing to do is not to unlock the 58 BLocker from the destructor once it is acquired. That way, any thread 59 waiting to do a AddMessage() will fail to acquire the lock since the 60 BLocker will be deleted before they can acquire it. 61*/ 62 63 64/*! 65 \fn void BMessageQueue::AddMessage(BMessage* message) 66 \brief Add a \a message to the end of the queue. 67 68 The message has to be allocated on the heap with \c new, because the queue 69 claims ownership of the message. Messages that were constructed on the 70 stack will corrupt the queue. 71 72 Because a BMessageQueue claims ownership of the \a message, it is important 73 that the message does not belong to another BMessageQueue. 74*/ 75 76 77/*! 78 \fn void BMessageQueue::RemoveMessage(BMessage* message) 79 \brief Remove a \a message from the queue. 80 81 If the \a message is indeed associated with this queue, it is removed from 82 it. This effectively means that you regain ownership of the message. 83*/ 84 85 86/*! 87 \fn int32 BMessageQueue::CountMessages() const 88 \brief Return the number of messages waiting in the queue. 89*/ 90 91 92/*! 93 \fn bool BMessageQueue::IsEmpty() const 94 \brief Check if there are messages waiting in the queue. 95*/ 96 97 98/*! 99 \fn BMessage *BMessageQueue::FindMessage(int32 index) const 100 \brief Retrieve the message at the \a index of this queue. 101 102 \param index A zero-based index of the message you want to retrieve. 103 104 \return A pointer to a message, or \c NULL if the \a index is out of 105 bounds. 106 \see FindMessage(uint32, int32) for a variant that takes a specific \c what 107 identifier. 108*/ 109 110 111/*! 112 \fn BMessage *BMessageQueue::FindMessage(uint32 what, int32 index) const 113 \brief Retrieve the message at the \a index of this queue, but only if it 114 has a specific \a what constant. 115 116 \param index A zero-based index of the message you want to retrieve. 117 \param what The \a what code of the message. 118 119 \return A pointer to a message, or \c NULL if there is no message at the 120 \a index with that \a what constant, or if the \a index is out of 121 bounds. 122*/ 123 124 125/*! 126 \fn bool BMessageQueue::Lock() 127 \brief Lock the queue so no other thread can perform operations on it. 128 129 \see Unlock() 130*/ 131 132 133/*! 134 \fn void BMessageQueue::Unlock() 135 \brief Unlock the queue after a Lock() request. 136 137 \see Lock() 138*/ 139 140 141/*! 142 \fn bool BMessageQueue::IsLocked() const 143 \brief Check if the queue is locked. 144 145 \see Lock() and Unlock() 146*/ 147 148 149/*! 150 \fn BMessage *BMessageQueue::NextMessage() 151 \brief Remove the first BMessage on the queue and return it to the caller. 152 153 After calling this method, you get the ownership of the message, so make 154 sure it is deleted after you are done. 155 156 \return A pointer to a message, or \c NULL if the queue is empty, or the 157 object has not been properly locked. 158 \see Lock() 159 \see IsNextMessage() 160*/ 161 162 163/*! 164 \fn bool BMessageQueue::IsNextMessage(const BMessage* message) const 165 \brief Check if the pointer to a \a message points at the next message on 166 the queue. 167*/ 168