docs/user/app/MessageQueue.dox

   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 */