NAME

ACE_Message_Queue - A thread-safe message queueing facility, modeled after the queueing facilities in System V StreamS.

SYNOPSIS


#include <ace/Message_Queue.h>


template<ACE_SYNCH_1>
class ACE_Message_Queue
{
  public:
        enum { DEFAULT_LWM = 0,
        DEFAULT_HWM = 16 * 1024,
        WAS_ACTIVE = 1,
        WAS_INACTIVE = 2 };
        
    ACE_Message_Queue (
        size_t hwm = DEFAULT_HWM,
        size_t lwm = DEFAULT_LWM
        );
    int open (size_t hwm = DEFAULT_HWM, size_t lwm = DEFAULT_LWM);
    int close (void);
    ~ACE_Message_Queue (void);
    int peek_dequeue_head (
        ACE_Message_Block *&first_item,
        ACE_Time_Value *tv = 0
        );
    int enqueue (ACE_Message_Block *new_item, ACE_Time_Value *tv = 0);
    int enqueue_tail (
        ACE_Message_Block *new_item,
        ACE_Time_Value *tv = 0
        );
    int enqueue_head (
        ACE_Message_Block *new_item,
        ACE_Time_Value *tv = 0
        );
    int dequeue_head (
        ACE_Message_Block *&first_item,
        ACE_Time_Value *tv = 0
        );
    int is_full (void);
    int is_empty (void);
    size_t message_bytes (void);
    size_t message_count (void);
    size_t high_water_mark (void);
    void high_water_mark (size_t hwm);
    size_t low_water_mark (void);
    void low_water_mark (size_t lwm);
    int deactivate (void);
    int activate (void);
    void dump (void) const;
    ACE_ALLOC_HOOK_DECLARE;
  protected:
    int enqueue_i (ACE_Message_Block *new_item);
    int enqueue_tail_i (ACE_Message_Block *new_item);
    int enqueue_head_i (ACE_Message_Block *new_item);
    int dequeue_head_i (ACE_Message_Block *&first_item);
    int is_full_i (void);
    int is_empty_i (void);
    int deactivate_i (void);
    int activate_i (void);
    ACE_Message_Block *head_;
    ACE_Message_Block *tail_;
    int low_water_mark_;
    int high_water_mark_;
    int cur_bytes_;
    int cur_count_;
    int deactivated_;
    ACE_SYNCH_MUTEX lock_;
    ACE_SYNCH_CONDITION notempty_cond_;
    ACE_SYNCH_CONDITION notfull_cond_;
};

DESCRIPTION

A ACE_Message_Queue is the central queueing facility for messages in the ASX framework. If ACE_SYNCH_1 is ACE_MT_SYNCH then all operations are thread-safe. Otherwise, if it's ACE_NULL_SYNCH then there's no locking overhead.

Default high and low water marks.

Initialization and termination methods.

ACE_Message_Queue (
    size_t hwm = DEFAULT_HWM,
    size_t lwm = DEFAULT_LWM
    );
int open (size_t hwm = DEFAULT_HWM, size_t lwm = DEFAULT_LWM);
int close (void);
~ACE_Message_Queue (void);
int peek_dequeue_head (
    ACE_Message_Block *&first_item,
    ACE_Time_Value *tv = 0
    );

For all the following three routines if tv == 0, the caller

will block until action is possible, else will wait for amount of time in *tv). Calls will return, however, when queue is closed, deactivated, when a signal occurs, or if the time specified in tv elapses, (in which case errno = EWOULDBLOCK).
int enqueue (ACE_Message_Block *new_item, ACE_Time_Value *tv = 0);
int enqueue_tail (
    ACE_Message_Block *new_item,
    ACE_Time_Value *tv = 0
    );
int enqueue_head (
    ACE_Message_Block *new_item,
    ACE_Time_Value *tv = 0
    );
int dequeue_head (
    ACE_Message_Block *&first_item,
    ACE_Time_Value *tv = 0
    );

Checks if queue is full/empty.

int is_full (void);
int is_empty (void);
size_t message_bytes (void);
size_t message_count (void);

Flow control routines

size_t high_water_mark (void);
void high_water_mark (size_t hwm);
size_t low_water_mark (void);
void low_water_mark (size_t lwm);

Activation control methods.

int deactivate (void);
int activate (void);
void dump (void) const;
ACE_ALLOC_HOOK_DECLARE;

Routines that actually do the enqueueing and dequeueing (these

assume that locks are held by the corresponding public methods).
int enqueue_i (ACE_Message_Block *new_item);
int enqueue_tail_i (ACE_Message_Block *new_item);
int enqueue_head_i (ACE_Message_Block *new_item);
int dequeue_head_i (ACE_Message_Block *&first_item);

Check the boundary conditions (assumes locks are held).

int is_full_i (void);
int is_empty_i (void);

Implementation of the public activate() and deactivate()

methods above (assumes locks are held).
int deactivate_i (void);
int activate_i (void);
ACE_Message_Block *head_;
ACE_Message_Block *tail_;
int low_water_mark_;
int high_water_mark_;
int cur_bytes_;
int cur_count_;
int deactivated_;

Synchronization primitives for controlling concurrent access.

ACE_SYNCH_MUTEX lock_;
ACE_SYNCH_CONDITION notempty_cond_;
ACE_SYNCH_CONDITION notfull_cond_;

AUTHOR

Doug Schmidt

LIBRARY

ace