diff --git a/docs/user/app/MessageQueue.dox b/docs/user/app/MessageQueue.dox new file mode 100644 index 0000000000..12c49140ba --- /dev/null +++ b/docs/user/app/MessageQueue.dox @@ -0,0 +1,164 @@ +/* + * Copyright 2007, Haiku, Inc. All Rights Reserved. + * Distributed under the terms of the MIT License. + * + * Authors: + * Niels Sascha Reedijk, niels.reedijk@gmail.com + * + * Corresponds to: + * /trunk/headers/os/app/MessageQueue.h rev 19956 + * /trunk/src/kits/app/MessageQueue.cpp rev 19956 + */ + +/*! + \file MessageQueue.h + \brief Provides the BMessageQueue class. +*/ + + +/*! + \class BMessageQueue + \ingroup app + \brief A container that maintains a queue of messages. + + This class is used by BLooper to maintain a queue of messages that need to + be processed. This class has been designed as a first in, first out + container. + + The default message handling of a BLooper probably suffices for most uses, + but if you want more control, you can perform operations using the methods + of this class. Use BLooper::MessageQueue() to retrieve the specific + BMessageQueue instance. + + Note that you are encouraged to make sure that whichever operation you + perform, that you only do this after the object has been locked (see + Lock()). The most important method, NextMessage() will fail if you have not + complied with this requirement. +*/ + + +/*! + \fn BMessageQueue::BMessageQueue() + \brief Constructs an empty message queue. +*/ + + +/*! + \fn BMessageQueue::~BMessageQueue() + \brief Destruct the BMessageQueue. It iterates over any messages left on + the queue and deletes them. + + The implementation is careful not to release the lock when the + BMessageQueue is deconstructed. If the lock is released, it is + possible another thread will start an AddMessage() operation before + the BLocker is deleted. The safe thing to do is not to unlock the + BLocker from the destructor once it is acquired. That way, any thread + waiting to do a AddMessage() will fail to acquire the lock since the + BLocker will be deleted before they can acquire it. +*/ + + +/*! + \fn void BMessageQueue::AddMessage(BMessage* message) + \brief Add a \a message to the end of the queue. + + The message has to be allocated on the heap with \c new, because the queue + claims ownership of the message. Messages that were constructed on the + stack will corrupt the queue. + + Because a BMessageQueue claims ownership of the \a message, it is important + that the message does not belong to another BMessageQueue. +*/ + + +/*! + \fn void BMessageQueue::RemoveMessage(BMessage* message) + \brief Remove a \a message from the queue. + + If the \a message is indeed associated with this queue, it is removed from + it. This effectively means that you regain ownership of the message. +*/ + + +/*! + \fn int32 BMessageQueue::CountMessages() const + \brief Return the number of messages waiting in the queue. +*/ + + +/*! + \fn bool BMessageQueue::IsEmpty() const + \brief Check if there are messages waiting in the queue. +*/ + + +/*! + \fn BMessage *BMessageQueue::FindMessage(int32 index) const + \brief Retrieve the message at the \a index of this queue. + + \param index A zero-based index of the message you want to retrieve. + + \return A pointer to a message, or \c NULL if the \a index is out of + bounds. + \see FindMessage(uint32, int32) for a variant that takes a specific \c what + identifier. +*/ + + +/*! + \fn BMessage *BMessageQueue::FindMessage(uint32 what, int32 index) const + \brief Retrieve the message at the \a index of this queue, but only if it + has a specific \a what constant. + + \param index A zero-based index of the message you want to retrieve. + \param what The \a what code of the message. + + \return A pointer to a message, or \c NULL if there is no message at the + \a index with that \a what constant, or if the \a index is out of + bounds. +*/ + + +/*! + \fn bool BMessageQueue::Lock() + \brief Lock the queue so no other thread can perform operations on it. + + \see Unlock() +*/ + + +/*! + \fn void BMessageQueue::Unlock() + \brief Unlock the queue after a Lock() request. + + \see Lock() +*/ + + +/*! + \fn bool BMessageQueue::IsLocked() const + \brief Check if the queue is locked. + + \see Lock() and Unlock() +*/ + + +/*! + \fn BMessage *BMessageQueue::NextMessage() + \brief Remove the first BMessage on the queue and return it to the caller. + + After calling this method, you get the ownership of the message, so make + sure it is deleted after you are done. + + \return A pointer to a message, or \c NULL if the queue is empty, or the + object has not been properly locked. + \see Lock() + \see IsNextMessage() +*/ + + +/*! + \fn bool BMessageQueue::IsNextMessage(const BMessage* message) const + \brief Check if the pointer to a \a message points at the next message on + the queue. +*/ diff --git a/src/kits/app/MessageQueue.cpp b/src/kits/app/MessageQueue.cpp index e9917adda8..4b3e5bbfbe 100644 --- a/src/kits/app/MessageQueue.cpp +++ b/src/kits/app/MessageQueue.cpp @@ -25,18 +25,6 @@ BMessageQueue::BMessageQueue() } -/*! - \brief This is the desctructor for the BMessageQueue. It iterates over - any messages left on the queue and deletes them. - - The implementation is careful not to release the lock when the - BMessageQueue is deconstructed. If the lock is released, it is - possible another thread will start an AddMessage() operation before - the BLocker is deleted. The safe thing to do is not to unlock the - BLocker from the destructor once it is acquired. That way, any thread - waiting to do a AddMessage() will fail to acquire the lock since the - BLocker will be deleted before they can acquire it. -*/ BMessageQueue::~BMessageQueue() { if (!Lock()) @@ -52,15 +40,6 @@ BMessageQueue::~BMessageQueue() } -/*! - \brief This method adds a BMessage to the queue. - - It makes a couple of assumptions: - - The BMessage was allocated on the heap with new, since the - destructor delete's BMessages left on the queue. - - The BMessage is not already on this or any other BMessageQueue. - If it is, the queue it is already on will be corrupted. -*/ void BMessageQueue::AddMessage(BMessage* message) { @@ -88,10 +67,6 @@ BMessageQueue::AddMessage(BMessage* message) } -/*! - \brief This method searches the queue for a particular BMessage. - If it is found, it is removed from the queue. -*/ void BMessageQueue::RemoveMessage(BMessage* message) { @@ -122,9 +97,6 @@ BMessageQueue::RemoveMessage(BMessage* message) } -/*! - \brief This method just returns the number of BMessages on the queue. -*/ int32 BMessageQueue::CountMessages() const { @@ -132,9 +104,6 @@ BMessageQueue::CountMessages() const } -/*! - \brief This method just returns true if there are no BMessages on the queue. -*/ bool BMessageQueue::IsEmpty() const { @@ -142,14 +111,6 @@ BMessageQueue::IsEmpty() const } -/*! - \brief This method searches the queue for the index'th BMessage. - - The first BMessage is at index 0, the second at index 1 etc. - The BMessage is returned if it is found. If no BMessage exists at that - index (ie the queue is not that long or the index is invalid) NULL is - returned. -*/ BMessage * BMessageQueue::FindMessage(int32 index) const { @@ -172,10 +133,6 @@ BMessageQueue::FindMessage(int32 index) const } -/*! - \brief Searches the queue for the index'th BMessage that has a - particular what code. -*/ BMessage * BMessageQueue::FindMessage(uint32 what, int32 index) const { @@ -200,10 +157,6 @@ BMessageQueue::FindMessage(uint32 what, int32 index) const } -/*! - \brief Locks the BMessageQueue so no other thread can change - or search the queue. -*/ bool BMessageQueue::Lock() { @@ -211,9 +164,6 @@ BMessageQueue::Lock() } -/*! - \brief Releases the lock which was acquired by Lock(). -*/ void BMessageQueue::Unlock() { @@ -221,9 +171,6 @@ BMessageQueue::Unlock() } -/*! - \brief Returns whether or not the queue is locked -*/ bool BMessageQueue::IsLocked() const { @@ -231,10 +178,6 @@ BMessageQueue::IsLocked() const } -/*! - \brief Removes the first BMessage on the queue and returns - it to the caller. If the queue is empty, NULL is returned. -*/ BMessage * BMessageQueue::NextMessage() { @@ -262,10 +205,6 @@ BMessageQueue::NextMessage() } -/*! - \brief Checks wether or not the specified \a message is the message - you would get when calling NextMessage(). -*/ bool BMessageQueue::IsNextMessage(const BMessage* message) const {