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