1 karl 1.38 //%2006////////////////////////////////////////////////////////////////////////
|
2 mike 1.4 //
|
3 karl 1.32 // Copyright (c) 2000, 2001, 2002 BMC Software; Hewlett-Packard Development
4 // Company, L.P.; IBM Corp.; The Open Group; Tivoli Systems.
5 // Copyright (c) 2003 BMC Software; Hewlett-Packard Development Company, L.P.;
|
6 karl 1.30 // IBM Corp.; EMC Corporation, The Open Group.
|
7 karl 1.32 // Copyright (c) 2004 BMC Software; Hewlett-Packard Development Company, L.P.;
8 // IBM Corp.; EMC Corporation; VERITAS Software Corporation; The Open Group.
|
9 karl 1.33 // Copyright (c) 2005 Hewlett-Packard Development Company, L.P.; IBM Corp.;
10 // EMC Corporation; VERITAS Software Corporation; The Open Group.
|
11 karl 1.38 // Copyright (c) 2006 Hewlett-Packard Development Company, L.P.; IBM Corp.;
12 // EMC Corporation; Symantec Corporation; The Open Group.
|
13 mike 1.4 //
14 // Permission is hereby granted, free of charge, to any person obtaining a copy
|
15 chip 1.11 // of this software and associated documentation files (the "Software"), to
16 // deal in the Software without restriction, including without limitation the
17 // rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
18 mike 1.4 // sell copies of the Software, and to permit persons to whom the Software is
19 // furnished to do so, subject to the following conditions:
|
20 karl 1.38 //
|
21 chip 1.11 // THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN
|
22 mike 1.4 // ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED
23 // "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
|
24 chip 1.11 // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
25 // PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
26 // HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
|
27 mike 1.4 // ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
28 // WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
29 //
30 //==============================================================================
31 //
32 // Author: Mike Brasher (mbrasher@bmc.com)
33 //
|
34 david.dillard 1.34 // Modified By: David Dillard, VERITAS Software Corp.
35 // (david.dillard@veritas.com)
|
36 aruran.ms 1.37 // Aruran, IBm (ashanmug@in.ibm.com) for Bug# 3475
|
37 mike 1.4 //
38 //%/////////////////////////////////////////////////////////////////////////////
39
40 #ifndef Pegasus_MessageQueue_h
41 #define Pegasus_MessageQueue_h
42
43 #include <Pegasus/Common/Config.h>
44 #include <Pegasus/Common/Message.h>
|
45 kumpf 1.28 #include <Pegasus/Common/InternalException.h>
|
46 chip 1.11 #include <Pegasus/Common/IPC.h>
47 #include <Pegasus/Common/Thread.h>
|
48 kumpf 1.27 #include <Pegasus/Common/Linkage.h>
|
49 mike 1.4
50 PEGASUS_NAMESPACE_BEGIN
51
52 /** The MessageQueue class represents a queue abstraction and is used by
53 modules to exchange messages. Methods are provided for enqueuing,
54 dequeuing, removing, iterating messages. Some methods are virtual and
55 may be overriden but subclasses to modify the behavior.
|
56 mike 1.14
57 <h1>A Word about Queue Ids</h1>
58
59 You may pass a specific queue id to the MessageQueue() constructor. The
60 default is to call MessageQueue::getNextQueueId() to obtain one. Only pass
61 queue ids generated by calling MessageQueue::getNextQueueId() to this
|
62 david.dillard 1.34 constructor. Otherwise, you might end up with two queues with the same
|
63 mike 1.14 queue id.
64
65 A technique we encourage, is to declare global queue ids like this:
66
|
67 mday 1.16 <pre>
68 extern const Uint32 GROCERY_QUEUE_ID;
69 </pre>
|
70 mike 1.14
71 And then define them like this:
72
|
73 mday 1.16 <pre>
74 const Uint32 GROCERY_QUEUE_ID = MessageQueue::getNextQueueId();
75 </pre>
|
76 mike 1.14
77 And then pass them to the constructor of MessageQueue (from the derived
78 class). In this way you will secure a unique constant identifier by which
79 you may refer to a queue later on.
80
81 <h1>A Word about using the find() Methods</h1>
82
83 There are two find() methods. One that takes a queue id and one that
84 takes a name. The time complexity of the former is O(1); whereas, the
85 time complexity of the latter is O(n). Therefore, use the queue id form
86 since it is more efficient.
|
87 mike 1.4 */
88 class PEGASUS_COMMON_LINKAGE MessageQueue
89 {
|
90 david.dillard 1.34 public:
|
91 mike 1.4
|
92 david.dillard 1.34 /** This constructor places this object on a queue table which is
93 maintained by this class. Each message queue has a queue-id (which
94 may be obtained by calling getQueueId()). The queue-id may be passed
95 to lookupQueue() to obtain a pointer to the corresponding queue).
96
97 @param queueId the queue id to be used by this object. ONLY PASS IN
98 QUEUE IDS WHICH WERE GENERATED USING MessageQueue::getNextQueueId().
99 Otherwise, you might end up with more than one queue with the same
100 queue id.
101 */
102 MessageQueue(
103 const char *name,
104 Boolean async = false,
105 Uint32 queueId = MessageQueue::getNextQueueId());
106
107 /** Removes this queue from the queue table. */
108 virtual ~MessageQueue();
109
110 /** Enques a message (places it at the back of the queue).
111 @param message pointer to message to be enqueued.
112 @exception NullPointer exception if message parameter is null.
113 david.dillard 1.34 @exception IPCException if socket call has an error
114 */
115 virtual void enqueue(Message* message);
116
117 /** allows a caller to determine if this message queue is asynchronous or
118 not.
119 */
120 virtual Boolean isAsync() const { return _async; }
121
122 /** Dequeues a message (removes it from the front of the queue).
123 @return pointer to message or zero if queue is empty.
124 @exception IPCException Thrown if an IPC error occurs.
125 */
126 virtual Message* dequeue();
127
128 /** Removes the given message from the queue.
129 @param message to be removed.
130 @exception throws NullPointer if message parameter is null.
131 @exception throws NoSuchMessageOnQueue is message paramter is not
132 @exception IPCException Thrown if an IPC error occurs.
133 on this queue.
134 david.dillard 1.34 */
135 virtual void remove(Message* message);
136
137 /** Find the message with the given type.
138 @parameter type type of message to be found.
139 @return pointer to message if found; null otherwise.
140 @exception IPCException Thrown if an IPC error occurs.
141 */
142 virtual Message* findByType(Uint32 type);
143
144 /** Const version of findByType().
145 @exception IPCException Thrown if an IPC error occurs.
146 */
147 virtual const Message* findByType(Uint32 type) const;
148
149 /** Find the message with the given key.
150 @parameter key key of message to be found.
151 @return pointer to message if found; null otherwise.
152 @exception IPCException Thrown if an IPC error occurs.
153 */
154 virtual Message* findByKey(Uint32 key);
155 david.dillard 1.34
156 /** Const version of findByKey().
157 @exception IPCException Thrown if an IPC error occurs.
158 */
159 virtual const Message* findByKey(Uint32 key) const;
160
161 /** Finds the messages with the given type and key.
162 @param type type of message to be found.
163 @param type key of message to be found.
164 @return pointer to message if found; null otherwise.
165 @exception IPCException Thrown if an IPC error occurs.
166 */
167 virtual Message* find(Uint32 type, Uint32 key);
168
169 /** Const version of find().
170 @exception IPCException Thrown if an IPC error occurs.
171 */
172 virtual const Message* find(Uint32 type, Uint32 key) const;
173
174 /** Returns pointer to front message. */
175 Message* front() throw() { return _front; }
176 david.dillard 1.34
177 /** Const version of front(). */
178 const Message* front() const throw() { return _front; }
179
180 /** Returns pointer to back message. */
181 Message* back() throw() { return _back; }
182
183 /** Const version of back(). */
184 const Message* back() const throw() { return _back; }
185
186 /** Returns true if there are no messages on the queue. */
187 Boolean isEmpty() const throw() { return _front == 0; }
188
189 /** Returns the number of messages on the queue. */
190 Uint32 getCount() const throw() { return _count; }
191
192 /** Retrieve the queue id for this queue. */
193 Uint32 getQueueId() const throw() { return _queueId; }
194
195 Uint32 get_capabilities() const throw()
196 {
197 david.dillard 1.34 return _capabilities;
198 }
199
|
200 joyce.j 1.35 #ifdef PEGASUS_DEBUG
|
201 david.dillard 1.34 /** Prints the contents of this queue by calling the print() method
202 of each message.
203 @param os stream onto which the output is placed.
204 @exception IPCException Thrown if an IPC error occurs.
205 */
206 void print(PEGASUS_STD(ostream)& os) const;
|
207 joyce.j 1.35 #endif
|
208 david.dillard 1.34
209 /** Provide a string name for this queue to be used by the print method.
210 */
211 const char* getQueueName() const;
212
213 /** This method is called after a message has been enqueued. This default
214 implementation does nothing. Derived classes may override this to
215 take some action each time a message is enqueued (for example, this
216 method could handle the incoming message in the thread of the caller
217 of enqueue()).
218 */
219 virtual void handleEnqueue() ;
220
221 /** This method <b>may</b> be called prior to enqueueing an message.
222 the message queue can inform the caller that it does not want
223 to handle the message by returning false **/
224
225 virtual Boolean messageOK(const Message *msg) { return true ;}
226
227 /** Lookup a message queue from a queue id. Note this is an O(1) operation.
228 @exception IPCException Thrown if an IPC error occurs.
229 david.dillard 1.34 */
230 static MessageQueue* lookup(Uint32 queueId);
231
232 /** Lookup a message given a queue name. NOte this is an O(N) operation.
233 @exception IPCException Thrown if an IPC error occurs.
234 */
235 static MessageQueue* lookup(const char *name);
236
237 /** Get the next available queue id. It always returns a non-zero
238 queue id an monotonically increases and finally wraps (to one)
239 after reaching the maximum unsigned 32 bit integer.
240 @exception IPCException Thrown if an IPC error occurs.
241 */
242 static Uint32 getNextQueueId();
243
|
244 aruran.ms 1.37 /** Put the queue id into the stack.
245 */
246 static void putQueueId(Uint32 queueId);
247
|
248 david.dillard 1.34 protected:
249 static void remove_myself(Uint32);
250
251 Mutex _mut;
252 Uint32 _queueId;
253 char *_name;
254 Uint32 _capabilities;
255
256 private:
257 Uint32 _count;
258 Message* _front;
259 Message* _back;
260 Boolean _async;
|
261 mike 1.4 };
262
|
263 chip 1.11 inline const Message* MessageQueue::findByType(Uint32 type) const
|
264 mike 1.4 {
|
265 david.dillard 1.34 return ((MessageQueue*)this)->findByType(type);
|
266 mike 1.4 }
267
268 inline const Message* MessageQueue::findByKey(Uint32 key) const
269 {
|
270 david.dillard 1.34 return ((MessageQueue*)this)->findByKey(key);
|
271 mike 1.4 }
272
273 inline const Message* MessageQueue::find(Uint32 type, Uint32 key) const
274 {
|
275 david.dillard 1.34 return ((MessageQueue*)this)->find(type, key);
|
276 mike 1.4 }
277
278 class NoSuchMessageOnQueue : public Exception
279 {
|
280 david.dillard 1.34 public:
281 NoSuchMessageOnQueue() : Exception("No such message on this queue") { }
|
282 mike 1.4 };
283
284 PEGASUS_NAMESPACE_END
285
286 #endif /* Pegasus_MessageQueue_h */
|
Return to
MessageQueue.h
CVS log
Up to [Pegasus] / pegasus / src / Pegasus / Common