Derived from: none
Declared in: <app/MessageQueue.h>
A BMessageQueue maintains a queue where arriving messages (BMessage objects) are temporarily stored as they wait to be dispatched. Every BLooper object uses a BMessageQueue to manage the flow of incoming messages; all messages delivered to the BLooper's thread are placed in the queue. The BLooper removes the oldest message from the queue, passes it to a BHandler, waits for the thread to finish its response, deletes the message, then returns to the queue to get the next message.
For the most part, applications can ignore the queue--that is, they can treat it as an implementation detail. Messages are delivered to a BLooper by calling its PostMessage() function, by constructing a BMessenger object and calling SendMessage(), or through a drag-and-drop operation. Each method of delivery puts the message in a port owned by the BLooper and then in the queue.
A BLooper calls upon a BHandler's MessageReceived() function--and other, message-specific hook functions--to handle the messages it takes from the queue. Applications can simply implement the functions that are called to respond to received messages and not bother about the mechanics of the message loop, port, and queue.
However, if necessary, you can manipulate the queue directly, or perhaps just look ahead to see what messages are coming. The BLooper has a MessageQueue() function that returns its BMessageQueue object.
See also: the BMessage class, BLooper::MessageQueue()
BMessageQueue(void)
Ensures that the queue starts out empty. Messages are placed in the queue by calling AddMessage() and are removed by calling NextMessage().
Each BLooper object constructs a BMessageQueue for itself; you don't need to construct one.
See also: AddMessage(), NextMessage()
virtual ~BMessageQueue(void)
Deletes all the objects in the queue and all the data structures used to manage the queue.
void AddMessage(BMessage *message)
Adds message to the queue.
See also: NextMessage()
int32 CountMessages(void) const
Returns the number of messages currently in the queue.
BMessage *FindMessage(uint32 what, int32 index = 0) const
BMessage *FindMessage(int32 index) const
Returns a pointer to the BMessage that's positioned in the queue at index, where indices begin at 0 and count only those messages that have what data members matching the what value passed as an argument. If a what argument is omitted, indices count all messages in the queue. If an index is omitted, the first message that matches the what constant is found. The lower the index, the longer the message has been in the queue.
If no message matches the specified what and index criteria, this function returns NULL.
The returned message is not removed from the queue.
See also: NextMessage()
bool IsEmpty(void) const
Returns true if the BMessageQueue contains no messages, and false if it has at least one.
See also: CountMessages()
bool Lock(void)
void Unlock(void)
These functions lock and unlock the BMessageQueue, so that another thread won't alter the contents of the queue while it's being read. Lock() doesn't return until it has the queue locked; it always returns true. Unlock() releases the lock so that someone else can lock it. Calls to these functions can be nested.
See also: BLooper::Lock()
BMessage *NextMessage(void)
Returns the next message--the message that has been in the queue the longest--and removes it from the queue. If the queue is empty, this function returns NULL.
void RemoveMessage(BMessage *message)
Removes a particular message from the queue and deletes it.
See also: FindMessage()
The Be Book, in lovely HTML, for the BeOS Preview Release.
Copyright © 1997 Be, Inc. All rights reserved.
Be is a registered trademark; BeOS, BeBox, BeWare, GeekPort, the Be logo, and the BeOS logo are trademarks of Be, Inc.
Last modified June 30, 1997.