root/haiku/trunk/docs/user/app/MessageQueue.dox

Revision 24522, 4.4 kB (checked in by nielx, 2 months ago) 
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.
Line 
1 /*
2  * Copyright 2007, Haiku, Inc. All Rights Reserved.
3  * Distributed under the terms of the MIT License.
4  *
5  * Authors:
6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
7  *
8  * Corresponds to:
9  *              /trunk/headers/os/app/MessageQueue.h  rev 19956
10  *              /trunk/src/kits/app/MessageQueue.cpp  rev 19956
11  */
12
13 /*!
14         \file MessageQueue.h
15         \brief Provides the BMessageQueue class.
16 */
17
18
19 /*!
20         \class BMessageQueue
21         \ingroup app
22         \brief A container that maintains a queue of messages.
23        
24         This class is used by BLooper to maintain a queue of messages that need to
25         be processed. This class has been designed as a first in, first out
26         container.
27        
28         The default message handling of a BLooper probably suffices for most uses,
29         but if you want more control, you can perform operations using the methods
30         of this class. Use BLooper::MessageQueue() to retrieve the specific
31         BMessageQueue instance.
32        
33         Note that you are encouraged to make sure that whichever operation you
34         perform, that you only do this after the object has been locked (see
35         Lock()). The most important method, NextMessage() will fail if you have not
36         complied with this requirement.
37 */
38
39
40 /*!
41         \fn BMessageQueue::BMessageQueue()
42         \brief Constructs an empty message queue.
43 */
44
45
46 /*!
47         \fn BMessageQueue::~BMessageQueue()
48         \brief Destruct the BMessageQueue. It iterates over any messages left on
49                 the queue and deletes them.
50
51         The implementation is careful not to release the lock when the
52         BMessageQueue is deconstructed.  If the lock is released, it is
53         possible another thread will start an AddMessage() operation before
54         the BLocker is deleted.  The safe thing to do is not to unlock the
55         BLocker from the destructor once it is acquired. That way, any thread
56         waiting to do a AddMessage() will fail to acquire the lock since the
57         BLocker will be deleted before they can acquire it.
58 */
59
60
61 /*!
62         \fn void BMessageQueue::AddMessage(BMessage* message)
63         \brief Add a \a message to the end of the queue.
64
65         The message has to be allocated on the heap with \c new, because the queue
66         claims ownership of the message. Messages that were constructed on the
67         stack will corrupt the queue.
68        
69         Because a BMessageQueue claims ownership of the \a message, it is important
70         that the message does not belong to another BMessageQueue.
71 */
72
73
74 /*!
75         \fn void BMessageQueue::RemoveMessage(BMessage* message)
76         \brief Remove a \a message from the queue.
77        
78         If the \a message is indeed associated with this queue, it is removed from
79         it. This effectively means that you regain ownership of the message.
80 */
81
82
83 /*!
84         \fn int32 BMessageQueue::CountMessages() const
85         \brief Return the number of messages waiting in the queue.
86 */
87
88
89 /*!
90         \fn bool BMessageQueue::IsEmpty() const
91         \brief Check if there are messages waiting in the queue.
92 */
93
94
95 /*!
96         \fn BMessage *BMessageQueue::FindMessage(int32 index) const
97         \brief Retrieve the message at the \a index of this queue.
98        
99         \param index A zero-based index of the message you want to retrieve.
100        
101         \return A pointer to a message, or \c NULL if the \a index is out of
102                 bounds.
103         \see FindMessage(uint32, int32) for a variant that takes a specific \c what
104                 identifier.
105 */
106
107
108 /*!
109         \fn BMessage *BMessageQueue::FindMessage(uint32 what, int32 index) const
110         \brief Retrieve the message at the \a index of this queue, but only if it
111                 has a specific \a what constant.
112
113         \param index A zero-based index of the message you want to retrieve.
114         \param what The \a what code of the message.
115        
116         \return A pointer to a message, or \c NULL if there is no message at the
117                 \a index with that \a what constant, or if the \a index is out of
118                 bounds.
119 */
120
121
122 /*!
123         \fn bool BMessageQueue::Lock()
124         \brief Lock the queue so no other thread can perform operations on it.
125        
126         \see Unlock()
127 */
128
129
130 /*!
131         \fn void BMessageQueue::Unlock()
132         \brief Unlock the queue after a Lock() request.
133        
134         \see Lock()
135 */
136
137
138 /*!
139         \fn bool BMessageQueue::IsLocked() const
140         \brief Check if the queue is locked.
141
142         \see Lock() and Unlock()
143 */
144
145
146 /*!
147         \fn BMessage *BMessageQueue::NextMessage()
148         \brief Remove the first BMessage on the queue and return it to the caller.
149        
150         After calling this method, you get the ownership of the message, so make
151         sure it is deleted after you are done.
152        
153         \return A pointer to a message, or \c NULL if the queue is empty, or the
154                 object has not been properly locked.
155         \see Lock()
156         \see IsNextMessage()
157 */
158
159
160 /*!
161         \fn bool BMessageQueue::IsNextMessage(const BMessage* message) const
162         \brief Check if the pointer to a \a message points at the next message on
163                 the queue.
164 */
Note: See TracBrowser for help on using the browser.