Public Member Functions | List of all members
BMessageQueue Class Reference

A container that maintains a queue of messages. More...

Public Member Functions

 BMessageQueue ()
 Constructs an empty message queue. More...
 
virtual ~BMessageQueue ()
 Destruct the BMessageQueue. It iterates over any messages left on the queue and deletes them. More...
 
void AddMessage (BMessage *message)
 Add a message to the end of the queue. More...
 
int32 CountMessages () const
 Return the number of messages waiting in the queue. More...
 
BMessageFindMessage (int32 index) const
 Retrieve the message at the index of this queue. More...
 
BMessageFindMessage (uint32 what, int32 index=0) const
 Retrieve the message at the index of this queue, but only if it has a specific what constant. More...
 
bool IsEmpty () const
 Check if there are messages waiting in the queue. More...
 
bool IsLocked () const
 Check if the queue is locked. More...
 
bool IsNextMessage (const BMessage *message) const
 Check if the pointer to a message points at the next message on the queue. More...
 
bool Lock ()
 Lock the queue so no other thread can perform operations on it. More...
 
BMessageNextMessage ()
 Remove the first BMessage on the queue and return it to the caller. More...
 
void RemoveMessage (BMessage *message)
 Remove a message from the queue. More...
 
void Unlock ()
 Unlock the queue after a Lock() request. More...
 

Detailed Description

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.

Since
BeOS R3

Constructor & Destructor Documentation

◆ BMessageQueue()

BMessageQueue::BMessageQueue ( )

Constructs an empty message queue.

Since
BeOS R3

◆ ~BMessageQueue()

BMessageQueue::~BMessageQueue ( )
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.

Since
BeOS R3

Member Function Documentation

◆ AddMessage()

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.

Since
BeOS R3

◆ CountMessages()

int32 BMessageQueue::CountMessages ( ) const

Return the number of messages waiting in the queue.

Since
BeOS R3

◆ FindMessage() [1/2]

BMessage * BMessageQueue::FindMessage ( int32  index) const

Retrieve the message at the index of this queue.

Parameters
indexA zero-based index of the message you want to retrieve.
Returns
A pointer to a message, or NULL if the index is out of bounds.
See also
FindMessage(uint32, int32) for a variant that takes a specific what identifier.
Since
BeOS R3

◆ FindMessage() [2/2]

BMessage * BMessageQueue::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.

Parameters
indexA zero-based index of the message you want to retrieve.
whatThe what code of the message.
Returns
A pointer to a message, or NULL if there is no message at the index with that what constant, or if the index is out of bounds.
Since
BeOS R3

◆ IsEmpty()

bool BMessageQueue::IsEmpty ( ) const

Check if there are messages waiting in the queue.

Since
BeOS R3

◆ IsLocked()

bool BMessageQueue::IsLocked ( ) const

Check if the queue is locked.

See also
Lock()
Unlock()
Since
Haiku R1

◆ IsNextMessage()

bool BMessageQueue::IsNextMessage ( const BMessage message) const

Check if the pointer to a message points at the next message on the queue.

Since
Haiku R1

◆ Lock()

bool BMessageQueue::Lock ( )

Lock the queue so no other thread can perform operations on it.

See also
Unlock()
Since
BeOS R3

◆ NextMessage()

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.

Returns
A pointer to a message, or NULL if the queue is empty, or the object has not been properly locked.
See also
Lock()
IsNextMessage()
Since
BeOS R3

◆ RemoveMessage()

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.

Since
BeOS R3

◆ Unlock()

void BMessageQueue::Unlock ( )

Unlock the queue after a Lock() request.

See also
Lock()
Since
BeOS R3