--- name: "ACE_Message_Queue_NT" section: "3" platform: "linux" package: "libace-doc" version: "5.0.7-4" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/ACE_Message_Queue_NT" --- # ACE\_Message\_Queue\_NT(3) Message Queue implementation using IO completion port on NT. ## NAME ACE\_Message\_Queue\_NT - Message Queue implementation using IO completion port on NT. ## SYNOPSIS ``` #include class ACE_Message_Queue_NT : public ACE_Message_Queue_Base { public: ACE_Message_Queue_NT ( size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM ); virtual int open ( size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM ); virtual int close (void); virtual ~ACE_Message_Queue_NT (void); virtual int enqueue_tail ( 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 dequeue_head ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); virtual int dequeue ( 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 max_threads (void); virtual int deactivate (void); virtual int activate (void); virtual int deactivated (void); virtual void dump (void) const; virtual ACE_HANDLE completion_port (void); ACE_ALLOC_HOOK_DECLARE; private: size_t max_cthrs_; size_t cur_thrs_; size_t cur_bytes_; size_t cur_length_; size_t cur_count_; ACE_Thread_Mutex lock_; int deactivated_; ACE_HANDLE completion_port_; inline ACE_UNIMPLEMENTED_FUNC ( void operator= (const ACE_Message_Queue_NT &) ); }; ``` ## DESCRIPTION Implementation of a strip-downed ACE\_Message\_Queue using NT's IO completion port mechanism. NOTE: \*Many\* ACE\_Message\_Queue features are not supported with this implementation, including: \* open method have different signatures. \* dequeue\_head \*requires\* that the ACE\_Message\_Block\ pointer argument point to an ACE\_Message\_Block that was\ allocated by the caller. \* peek\_dequeue\_head. \* ACE\_Message\_Queue\_Iterators. \* No flow control. ## Initialization and termination methods. ``` ACE_Message_Queue_NT ( size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM ); ``` ``` virtual int open ( size_t max_threads = ACE_Message_Queue_Base::DEFAULT_HWM ); ``` Initialize the Message Queue by creating a new NT I/O completion port. The first arguemnt specifies the number of threads released by the MQ that are allowed to run concurrently. Return 0 when succeeds, -1 otherwise. ``` virtual int close (void); ``` Close down the underlying I/O completion port. You need to re-open the MQ after this function is executed. ``` virtual ~ACE_Message_Queue_NT (void); ``` Close down the message queue and release all resources. ## Enqueue and dequeue methods. ``` virtual int enqueue_tail ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); ``` ``` virtual int enqueue ( ACE_Message_Block *new_item, ACE_Time_Value *timeout = 0 ); ``` Enqueue an ACE\_Message\_Block \* at the end of the queue. Returns -1 on failure, else the number of items still on the queue. ``` virtual int dequeue_head ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); ``` ``` virtual int dequeue ( ACE_Message_Block *&first_item, ACE_Time_Value *timeout = 0 ); ``` Dequeue and return the ACE\_Message\_Block \* at the head of the queue. Returns -1 on failure, else the number of items still on the queue. ## Check if queue is full/empty. ``` virtual int is_full (void); ``` Always return false. ``` virtual int is_empty (void); ``` True if queue is empty, else false. Notice the return value is only transient. ## Queue statistic methods (transient.) ``` virtual size_t message_bytes (void); ``` Number of total bytes on the queue, i.e., sum of the message block sizes. ``` virtual size_t message_length (void); ``` Number of total length on the queue, i.e., sum of the message block lengths. ``` virtual size_t message_count (void); ``` Number of total messages on the queue. ## Manual changes to these stats (used when queued message blocks change size or lengths). ``` virtual void message_bytes (size_t new_size); ``` New value of the number of total bytes on the queue, i.e., sum of the message block sizes. ``` virtual void message_length (size_t new_length); ``` New value of the number of total length on the queue, i.e., sum of the message block lengths. ``` virtual size_t max_threads (void); ``` Get the max concurrent thread number. ## Activation control methods. ``` virtual int deactivate (void); ``` Deactivate the queue and wakeup all threads waiting on the queue so they can continue. Messages already in the queue get removed. If there are more messages in the queue than there are threads waiting on the queue, the left over messages will not be removed. Any other enqueue/dequeue operations called until the queue is activated again will immediately return -1 with errno == ESHUTDOWN. Returns WAS\_INACTIVE if queue was inactive before the call and WAS\_ACTIVE if queue was active before the call. ``` virtual int activate (void); ``` Reactivate the queue so that threads can enqueue and dequeue messages again. Returns WAS\_INACTIVE if queue was inactive before the call and WAS\_ACTIVE if queue was active before the call. ``` virtual int deactivated (void); ``` Returns true if deactivated\_ is enabled. ## Notification hook. ``` virtual void dump (void) const; ``` Dump the state of an object. ``` virtual ACE_HANDLE completion_port (void); ``` Get the handle to the underlying completion port. ``` ACE_ALLOC_HOOK_DECLARE; ``` Declare the dynamic allocation hooks. ## Internal states. ``` size_t max_cthrs_; ``` Maximum threads that can be released (and run) concurrently. ``` size_t cur_thrs_; ``` Current number of threads waiting to dequeue messages. ``` size_t cur_bytes_; ``` Current number of bytes in queue. ``` size_t cur_length_; ``` Current length of messages in queue. ``` size_t cur_count_; ``` Current number of messages in the queue. ``` ACE_Thread_Mutex lock_; ``` Synchronizer. This should really be an ACE\_Recursive\_Thread\_Mutex but since this class is only supported on NT, it's okay to use ACE\_Thread\_Mutex here. ``` int deactivated_; ``` Indicates that the queue is inactive. ``` ACE_HANDLE completion_port_; ``` Underlying NT IoCompletionPort. ## Disallow these operations. ``` inline ACE_UNIMPLEMENTED_FUNC ( void operator= (const ACE_Message_Queue_NT &) ); ``` ## AUTHOR Doug Schmidt ## LIBRARY ace