NAME

ACE_Message_Queue - A threaded message queueing facility, modeled after the queueing facilities in System V STREAMs.

SYNOPSIS

#include <ace/Message_Queue_T.h>

template<ACE_SYNCH_DECL> class ACE_Message_Queue : public ACE_Message_Queue_Base { public: friend class ACE_Message_Queue_Iterator<ACE_SYNCH_USE>; friend class ACE_Message_Queue_Reverse_Iterator<ACE_SYNCH_USE>; typedef ACE_Message_Queue_Iterator<ACE_SYNCH_USE> ITERATOR; typedef ACE_Message_Queue_Reverse_Iterator<ACE_SYNCH_USE> REVERSE_ITERATOR; ACE_Message_Queue ( 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 * = 0 ); virtual int open ( size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM, size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM, ACE_Notification_Strategy * = 0 ); virtual int close (void); virtual ~ACE_Message_Queue (void); virtual int peek_dequeue_head ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); virtual int enqueue_prio ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); virtual int enqueue ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); virtual int enqueue_tail ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); virtual int enqueue_head ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); virtual int dequeue ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); virtual int dequeue_head ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); virtual int is_full (void); virtual int is_empty (void); virtual size_t message_bytes (void); virtual size_t message_length (void); virtual size_t message_count (void); virtual void message_bytes (size_t new_size); virtual void message_length (size_t new_length); virtual size_t high_water_mark (void); virtual void high_water_mark (size_t hwm); virtual size_t low_water_mark (void); virtual void low_water_mark (size_t lwm); virtual int deactivate (void); virtual int activate (void); virtual int deactivated (void); virtual int notify (void); virtual ACE_Notification_Strategy *notification_strategy (void); virtual void notification_strategy (ACE_Notification_Strategy *s); ACE_SYNCH_MUTEX_T &lock (void); virtual void dump (void) const; ACE_ALLOC_HOOK_DECLARE; protected: virtual int enqueue_i (ACE_Message_Block *new_item); virtual int enqueue_tail_i (ACE_Message_Block *new_item); virtual int enqueue_head_i (ACE_Message_Block *new_item); virtual int dequeue_head_i (ACE_Message_Block *&first_item); virtual int is_full_i (void); virtual int is_empty_i (void); virtual int deactivate_i (void); virtual int activate_i (void); virtual int wait_not_full_cond ( ACE_Guard<ACE_SYNCH_MUTEX_T> &mon, ACE_Time_Value *timeout ); virtual int wait_not_empty_cond ( ACE_Guard<ACE_SYNCH_MUTEX_T> &mon, ACE_Time_Value *timeout ); virtual int signal_enqueue_waiters (void); virtual int signal_dequeue_waiters (void); ACE_Message_Block *head_; ACE_Message_Block *tail_; size_t low_water_mark_; size_t high_water_mark_; size_t cur_bytes_; size_t cur_length_; size_t cur_count_; int deactivated_; ACE_Notification_Strategy *notification_strategy_; ACE_SYNCH_MUTEX_T lock_; ACE_SYNCH_SEMAPHORE_T not_empty_cond_; ACE_SYNCH_SEMAPHORE_T not_full_cond_; size_t dequeue_waiters_; size_t enqueue_waiters_; ACE_SYNCH_CONDITION_T not_empty_cond_; ACE_SYNCH_CONDITION_T not_full_cond_; private: inline ACE_UNIMPLEMENTED_FUNC ( void operator= (const ACE_Message_Queue<ACE_SYNCH_USE> &) ); };

DESCRIPTION

An ACE_Message_Queue is the central queueing facility for messages in the ASX framework. 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.

Traits

typedef ACE_Message_Queue_Iterator<ACE_SYNCH_USE> ITERATOR;

    typedef ACE_Message_Queue_Reverse_Iterator<ACE_SYNCH_USE> REVERSE_ITERATOR;
    

Initialization and termination methods.

ACE_Message_Queue (
    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 * = 0
    );

virtual int open (
    size_t hwm = ACE_Message_Queue_Base::DEFAULT_HWM,
    size_t lwm = ACE_Message_Queue_Base::DEFAULT_LWM,
    ACE_Notification_Strategy * = 0
    );

virtual int close (void);

virtual ~ACE_Message_Queue (void);

Enqueue and dequeue methods.

For the following enqueue and dequeue methods if timeout == 0, the caller will block until action is possible, else will wait until the absolute time specified in *timeout elapses). These calls will return, however, when queue is closed, deactivated, when a signal occurs, or if the time specified in timeout elapses, (in which case errno = EWOULDBLOCK).
virtual int peek_dequeue_head (
    ACE_Message_Block *&first_item,
    ACE_Time_Value *timeout = 0
    );

virtual int enqueue_prio (
    ACE_Message_Block *new_item,
    ACE_Time_Value *timeout = 0
    );

virtual int enqueue (
    ACE_Message_Block *new_item,
    ACE_Time_Value *timeout = 0
    );

virtual int enqueue_tail (
    ACE_Message_Block *new_item,
    ACE_Time_Value *timeout = 0
    );

virtual int enqueue_head (
    ACE_Message_Block *new_item,
    ACE_Time_Value *timeout = 0
    );

virtual int dequeue (
    ACE_Message_Block *&first_item,
    ACE_Time_Value *timeout = 0
    );

virtual int dequeue_head (
    ACE_Message_Block *&first_item,
    ACE_Time_Value *timeout = 0
    );

Check if queue is full/empty.

virtual int is_full (void);

virtual int is_empty (void);

Queue statistic methods.

virtual size_t message_bytes (void);

virtual size_t message_length (void);

virtual size_t message_count (void);

Manual changes to these stats (used when queued message blocks

change size or lengths).
virtual void message_bytes (size_t new_size);

virtual void message_length (size_t new_length);

Flow control methods.

virtual size_t high_water_mark (void);

virtual void high_water_mark (size_t hwm);

virtual size_t low_water_mark (void);

virtual void low_water_mark (size_t lwm);

Activation control methods.

virtual int deactivate (void);

virtual int activate (void);

virtual int deactivated (void);

Notification hook.

virtual int notify (void);

= Get/set the notification strategy for the Message_Queue

virtual ACE_Notification_Strategy *notification_strategy (void);

virtual void notification_strategy (ACE_Notification_Strategy *s);

ACE_SYNCH_MUTEX_T &lock (void);

virtual void dump (void) const;

ACE_ALLOC_HOOK_DECLARE;

Routines that actually do the enqueueing and dequeueing.

These routines assume that locks are held by the corresponding public methods. Since they are virtual, you can change the queueing mechanism by subclassing from ACE_Message_Queue.
virtual int enqueue_i (ACE_Message_Block *new_item);

virtual int enqueue_tail_i (ACE_Message_Block *new_item);

virtual int enqueue_head_i (ACE_Message_Block *new_item);

virtual int dequeue_head_i (ACE_Message_Block *&first_item);

Check the boundary conditions (assumes locks are held).

virtual int is_full_i (void);

virtual int is_empty_i (void);

= Implementation of the public activate and deactivate methods. These methods assume locks are held.

virtual int deactivate_i (void);

virtual int activate_i (void);

Helper methods to factor out common #ifdef code.

virtual int wait_not_full_cond (
    ACE_Guard<ACE_SYNCH_MUTEX_T> &mon,
    ACE_Time_Value *timeout
    );

virtual int wait_not_empty_cond (
    ACE_Guard<ACE_SYNCH_MUTEX_T> &mon,
    ACE_Time_Value *timeout
    );

virtual int signal_enqueue_waiters (void);

virtual int signal_dequeue_waiters (void);

ACE_Message_Block *head_;

ACE_Message_Block *tail_;

size_t low_water_mark_;

size_t high_water_mark_;

size_t cur_bytes_;

size_t cur_length_;

size_t cur_count_;

int deactivated_;

ACE_Notification_Strategy *notification_strategy_;

Synchronization primitives for controlling concurrent access.

ACE_SYNCH_MUTEX_T lock_;

ACE_SYNCH_SEMAPHORE_T not_empty_cond_;

ACE_SYNCH_SEMAPHORE_T not_full_cond_;

size_t dequeue_waiters_;

size_t enqueue_waiters_;

ACE_SYNCH_CONDITION_T not_empty_cond_;

ACE_SYNCH_CONDITION_T not_full_cond_;

Disallow these operations.

inline ACE_UNIMPLEMENTED_FUNC (
    void operator= (const ACE_Message_Queue<ACE_SYNCH_USE> &)
    );

AUTHOR

Doug Schmidt

LIBRARY

ace