First version of the BMessageQueue documentation.
Note: I have cleared the original MessageQueue.cpp file from the inline documentation. When the storage kit comes up, we need to rediscuss the documentation policy. git-svn-id: file:///srv/svn/repos/haiku/haiku/trunk@24522 a95241bf-73f2-0310-859d-f6bbb57e9c96
This commit is contained in:
Niels Sascha Reedijk
parent
bd937035c7
commit
ce9ba9b376
164
docs/user/app/MessageQueue.dox
Normal file
164
docs/user/app/MessageQueue.dox
Normal file
@ -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.
|
||||
*/
|
||||
@ -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
|
||||
{
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user