Derived from: public BObject
Declared in: <app/MessageQueue.h>
A BMessageQueue maintains a queue where messages (BMessage objects) are temporarily stored as they wait to be received in a message loop. 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 posted to a thread (placed in the queue) by calling BLooper's PostMessage() function. Or they can be sent to the main thread of another application by constructing a BMessenger object and calling SendMessage() .
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 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().
BMessageQueues are constructed by BLooper objects.
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()
long CountMessages(void) const
Returns the number of messages currently in the queue.
BMessage *FindMessage(ulong what, long index = 0) const BMessage *FindMessage(long 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, HTML Edition, for Developer Release 8 of the Be Operating System.
Copyright © 1996 Be, Inc. All rights reserved.
Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.
Last modified September 6, 1996.