ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, > Class Template Reference

A threaded message queueing facility, modeled after the queueing facilities in System V STREAMs which can enqueue multiple messages in one call. More...

#include <Message_Queue_T.h>

Inheritance diagram for ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >:

Inheritance graph
[legend]
Collaboration diagram for ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >:

Collaboration graph
[legend]
List of all members.

Public Member Functions

 ACE_Message_Queue_Ex_N (size_t high_water_mark=ACE_Message_Queue_Base::DEFAULT_HWM, size_t low_water_mark=ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy *ns=0)
virtual ~ACE_Message_Queue_Ex_N (void)
 Close down the message queue and release all resources.

virtual int enqueue_head (ACE_MESSAGE_TYPE *new_item, ACE_Time_Value *tv=0)
virtual int enqueue_tail (ACE_MESSAGE_TYPE *new_item, ACE_Time_Value *tv=0)

Public Attributes

 ACE_ALLOC_HOOK_DECLARE
 Declare the dynamic allocation hooks.


Protected Member Functions

ACE_Message_Blockwrap_with_mbs_i (ACE_MESSAGE_TYPE *new_item)

Detailed Description

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL>
class ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >

A threaded message queueing facility, modeled after the queueing facilities in System V STREAMs which can enqueue multiple messages in one call.

As ACE_Message_Queue_Ex, ACE_Message_Queue_Ex_N is a strongly-typed version of the ACE_Message_Queue. If ACE_SYNCH_DECL is ACE_MT_SYNCH then all operations are thread-safe. Otherwise, if it's ACE_NULL_SYNCH then there's no locking overhead.

The ACE_MESSAGE_TYPE messages that are sent to this queue can be chained. Messages are expected to have a next method that returns the next message in the chain; ACE_Message_Queue_Ex_N uses this method to run through all the incoming messages and enqueue them in one call.

Definition at line 1382 of file Message_Queue_T.h.


Constructor & Destructor Documentation

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::ACE_Message_Queue_Ex_N size_t  high_water_mark = ACE_Message_Queue_Base::DEFAULT_HWM,
size_t  low_water_mark = ACE_Message_Queue_Base::DEFAULT_LWM,
ACE_Notification_Strategy ns = 0
 

Initialize an ACE_Message_Queue_Ex_N. The high_water_mark determines how many bytes can be stored in a queue before it's considered "full." Supplier threads must block until the queue is no longer full. The low_water_mark determines how many bytes must be in the queue before supplier threads are allowed to enqueue additional messages. By default, the high_water_mark equals the low_water_mark, which means that suppliers will be able to enqueue new messages as soon as a consumer removes any message from the queue. Making the low_water_mark smaller than the high_water_mark forces consumers to drain more messages from the queue before suppliers can enqueue new messages, which can minimize the "silly window syndrome."

Definition at line 338 of file Message_Queue_T.cpp.

References ACE_TRACE.

00340                                  :
00341     ACE_Message_Queue_Ex<ACE_MESSAGE_TYPE, ACE_SYNCH_USE> (high_water_mark,
00342                                                            low_water_mark,
00343                                                            ns)
00344 {
00345   ACE_TRACE ("ACE_Message_Queue_Ex_N<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::ACE_Message_Queue_Ex_N");
00346 }

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::~ACE_Message_Queue_Ex_N void   )  [virtual]
 

Close down the message queue and release all resources.

Definition at line 349 of file Message_Queue_T.cpp.

References ACE_TRACE.

00350 {
00351   ACE_TRACE ("ACE_Message_Queue_Ex_N<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::~ACE_Message_Queue_Ex_N");
00352 }


Member Function Documentation

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
int ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::enqueue_head ACE_MESSAGE_TYPE *  new_item,
ACE_Time_Value tv = 0
[virtual]
 

Enqueue one or more ACE_MESSAGE_TYPE objects at the head of the queue. If the new_item next() pointer is non-zero, it is assumed to be the start of a series of ACE_MESSAGE_TYPE objects connected via their next() pointers. The series of blocks will be added to the queue in the same order they are passed in as.

Parameters:
new_item Pointer to an ACE_MESSAGE_TYPE that will be added to the queue. If the block's next() pointer is non-zero, all blocks chained from the next() pointer are enqueued as well.
tv The absolute time the caller will wait until for the block to be queued.
Return values:
>0 The number of ACE_MESSAGE_TYPE objects on the queue after adding the specified block(s).
-1 On failure. errno holds the reason. Common errno values are:
  • EWOULDBLOCK: the timeout elapsed
  • ESHUTDOWN: the queue was deactivated or pulsed

Reimplemented from ACE_Message_Queue_Ex< ACE_MESSAGE_TYPE, ACE_SYNCH_USE >.

Definition at line 356 of file Message_Queue_T.cpp.

References ACE_TRACE, and ACE_Message_Block::release().

00358 {
00359   ACE_TRACE ("ACE_Message_Queue_Ex_N<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::enqueue_head");
00360 
00361   // Create a chained ACE_Message_Blocks wrappers around the 'chained'
00362   // ACE_MESSAGE_TYPES.
00363   ACE_Message_Block *mb = this->wrap_with_mbs_i (new_item);
00364   if (0 == mb)
00365     {
00366       return -1;
00367     }
00368 
00369   int result = this->queue_.enqueue_head (mb, timeout);
00370   if (-1 == result)
00371     {
00372       // Zap the messages.
00373       mb->release ();
00374     }
00375   return result;
00376 }

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
int ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::enqueue_tail ACE_MESSAGE_TYPE *  new_item,
ACE_Time_Value tv = 0
[virtual]
 

Enqueue one or more ACE_MESSAGE_TYPE objects at the tail of the queue. If the new_item next() pointer is non-zero, it is assumed to be the start of a series of ACE_MESSAGE_TYPE objects connected via their next() pointers. The series of blocks will be added to the queue in the same order they are passed in as.

Parameters:
new_item Pointer to an ACE_MESSAGE_TYPE that will be added to the queue. If the block's next() pointer is non-zero, all blocks chained from the next() pointer are enqueued as well.
tv The absolute time the caller will wait until for the block to be queued.
Return values:
>0 The number of ACE_MESSAGE_TYPE objects on the queue after adding the specified block(s).
-1 On failure. errno holds the reason. Common errno values are:
  • EWOULDBLOCK: the timeout elapsed
  • ESHUTDOWN: the queue was deactivated or pulsed

Reimplemented from ACE_Message_Queue_Ex< ACE_MESSAGE_TYPE, ACE_SYNCH_USE >.

Definition at line 380 of file Message_Queue_T.cpp.

References ACE_TRACE, and ACE_Message_Block::release().

00382 {
00383   ACE_TRACE ("ACE_Message_Queue_Ex_N<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::enqueue_tail");
00384 
00385   // Create a chained ACE_Message_Blocks wrappers around the 'chained'
00386   // ACE_MESSAGE_TYPES.
00387   ACE_Message_Block *mb = this->wrap_with_mbs_i (new_item);
00388   if (0 == mb)
00389     {
00390       return -1;
00391     }
00392 
00393   int result = this->queue_.enqueue_tail (mb, timeout);
00394   if (-1 == result)
00395     {
00396       // Zap the message.
00397       mb->release ();
00398     }
00399   return result;
00400 }

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
ACE_Message_Block * ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::wrap_with_mbs_i ACE_MESSAGE_TYPE *  new_item  )  [protected]
 

An helper method that wraps the incoming chain messages with ACE_Message_Blocks.

Definition at line 404 of file Message_Queue_T.cpp.

References ACE_NEW_NORETURN, ACE_NEW_RETURN, ACE_TRACE, ACE_Message_Block::next(), and ACE_Message_Block::release().

00405 {
00406   ACE_TRACE ("ACE_Message_Queue_Ex_N<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::wrap_with_mbs_i");
00407 
00408   // We need to keep a reference to the head of the chain
00409   ACE_Message_Block *mb_head = 0;
00410 
00411   ACE_NEW_RETURN (mb_head,
00412                   ACE_Message_Block ((char *) new_item,
00413                                      sizeof (*new_item),
00414                                      ACE_Message_Queue_Ex<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::DEFAULT_PRIORITY),
00415                   0);
00416 
00417   // mb_tail will point to the last ACE_Message_Block
00418   ACE_Message_Block *mb_tail = mb_head;
00419 
00420   // Run through rest of the messages and wrap them
00421   for (ACE_MESSAGE_TYPE *pobj = new_item->next (); pobj; pobj = pobj->next ())
00422     {
00423       ACE_Message_Block *mb_temp = 0;
00424       ACE_NEW_NORETURN (mb_temp,
00425                         ACE_Message_Block ((char *) pobj,
00426                                            sizeof (*pobj),
00427                                            ACE_Message_Queue_Ex<ACE_MESSAGE_TYPE, ACE_SYNCH_USE>::DEFAULT_PRIORITY));
00428       if (mb_temp == 0)
00429         {
00430           mb_head->release ();
00431           mb_head = 0;
00432           break;
00433         }
00434 
00435       mb_tail->next (mb_temp);
00436       mb_tail = mb_temp;
00437     }
00438 
00439   return mb_head;
00440 }


Member Data Documentation

template<class ACE_MESSAGE_TYPE, ACE_SYNCH_DECL >
ACE_Message_Queue_Ex_N< ACE_MESSAGE_TYPE, >::ACE_ALLOC_HOOK_DECLARE
 

Declare the dynamic allocation hooks.

Reimplemented from ACE_Message_Queue_Ex< ACE_MESSAGE_TYPE, ACE_SYNCH_USE >.

Definition at line 1453 of file Message_Queue_T.h.


The documentation for this class was generated from the following files:
Generated on Sun Jan 27 12:55:53 2008 for ACE by doxygen 1.3.6