A container that maintains a queue of messages. More...
Public Member Functions | |
| BMessageQueue () | |
| Constructs an empty message queue. | |
| virtual | ~BMessageQueue () |
| Destruct the BMessageQueue. It iterates over any messages left on the queue and deletes them. | |
| void | AddMessage (BMessage *message) |
| Add a message to the end of the queue. | |
| int32 | CountMessages () const |
| Return the number of messages waiting in the queue. | |
| BMessage * | FindMessage (int32 index) const |
| Retrieve the message at the index of this queue. | |
| BMessage * | FindMessage (uint32 what, int32 index=0) const |
| Retrieve the message at the index of this queue, but only if it has a specific what constant. | |
| bool | IsEmpty () const |
| Check if there are messages waiting in the queue. | |
| bool | IsLocked () const |
| Check if the queue is locked. | |
| bool | IsNextMessage (const BMessage *message) const |
| Check if the pointer to a message points at the next message on the queue. | |
| bool | Lock () |
| Lock the queue so no other thread can perform operations on it. | |
| BMessage * | NextMessage () |
| Remove the first BMessage on the queue and return it to the caller. | |
| void | RemoveMessage (BMessage *message) |
| Remove a message from the queue. | |
| void | Unlock () |
| Unlock the queue after a Lock() request. | |
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.
| BMessageQueue::BMessageQueue | ( | ) |
Constructs an empty message queue.
|
virtual |
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.
| void BMessageQueue::AddMessage | ( | BMessage * | message | ) |
Add a message to the end of the queue.
The message has to be allocated on the heap with 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 message, it is important that the message does not belong to another BMessageQueue.
| int32 BMessageQueue::CountMessages | ( | ) | const |
Return the number of messages waiting in the queue.
Retrieve the message at the index of this queue.
| index | A zero-based index of the message you want to retrieve. |
NULL if the index is out of bounds. what identifier.Retrieve the message at the index of this queue, but only if it has a specific what constant.
| index | A zero-based index of the message you want to retrieve. |
| what | The what code of the message. |
NULL if there is no message at the index with that what constant, or if the index is out of bounds.| bool BMessageQueue::IsEmpty | ( | ) | const |
Check if there are messages waiting in the queue.
| bool BMessageQueue::IsLocked | ( | ) | const |
| bool BMessageQueue::IsNextMessage | ( | const BMessage * | message | ) | const |
Check if the pointer to a message points at the next message on the queue.
| bool BMessageQueue::Lock | ( | ) |
| BMessage * BMessageQueue::NextMessage | ( | ) |
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.
NULL if the queue is empty, or the object has not been properly locked.| void BMessageQueue::RemoveMessage | ( | BMessage * | message | ) |
Remove a message from the queue.
If the message is indeed associated with this queue, it is removed from it. This effectively means that you regain ownership of the message.