Changeset 24522

Timestamp:

03/22/08 10:36:20 (8 months ago)

Author:

nielx

Message:

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.

Location:

haiku/trunk

Files:

• docs/user/app/MessageQueue.dox (added)
• src/kits/app/MessageQueue.cpp (modified) (12 diffs)

haiku/trunk/src/kits/app/MessageQueue.cpp

@@ -26 +26 @@
 
 
-/*!
-        \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()
 {
@@ -53 +41 @@
 
 
-/*!
-        \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)
@@ -89 +68 @@
 
 
-/*!
-        \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)
@@ -123 +98 @@
 
 
-/*!
-        \brief This method just returns the number of BMessages on the queue.
-*/
 int32
 BMessageQueue::CountMessages() const
@@ -133 +105 @@
 
 
-/*!
-        \brief This method just returns true if there are no BMessages on the queue.
-*/
 bool
 BMessageQueue::IsEmpty() const
@@ -143 +112 @@
 
 
-/*!
-        \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
@@ -173 +134 @@
 
 
-/*!
-        \brief Searches the queue for the index'th BMessage that has a
-                particular what code.
-*/
 BMessage *
 BMessageQueue::FindMessage(uint32 what, int32 index) const
@@ -201 +158 @@
 
 
-/*!
-        \brief Locks the BMessageQueue so no other thread can change
-                or search the queue.
-*/
 bool
 BMessageQueue::Lock()
@@ -212 +165 @@
 
 
-/*!
-        \brief Releases the lock which was acquired by Lock().
-*/
 void
 BMessageQueue::Unlock()
@@ -222 +172 @@
 
 
-/*!
-        \brief Returns whether or not the queue is locked
-*/
 bool
 BMessageQueue::IsLocked() const
@@ -232 +179 @@
 
 
-/*!
-        \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()
@@ -263 +206 @@
 
 
-/*!
-        \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