--- name: "ACE_Task" 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_Task" --- # ACE\_Task(3) Primary interface for application message processing, as well as input and output message queueing. ## NAME ACE\_Task - Primary interface for application message processing, as well as input and output message queueing. ## SYNOPSIS ``` #include template class ACE_Task : public ACE_Task_Base { public: friend class ACE_Module; friend class ACE_Module_Type; ACE_Task ( ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue *mq = 0 ); virtual ~ACE_Task (void); ACE_Message_Queue *msg_queue (void); void msg_queue (ACE_Message_Queue *); int putq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); int getq (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0); int ungetq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); int reply (ACE_Message_Block *, ACE_Time_Value *timeout = 0); int put_next ( ACE_Message_Block *msg, ACE_Time_Value *timeout = 0 ); int can_put (ACE_Message_Block *); const ASYS_TCHAR *name (void) const; ACE_Task *next (void); void next (ACE_Task *); ACE_Task *sibling (void); ACE_Module *module (void) const; int flush (u_long flag = ACE_Task_Flags::ACE_FLUSHALL); void water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t); ACE_Message_Queue *msg_queue_; int delete_msg_queue_; ACE_Module *mod_; ACE_Task *next_; void dump (void) const; ACE_ALLOC_HOOK_DECLARE; private: inline ACE_UNIMPLEMENTED_FUNC ( void operator= (const ACE_Task &) ); }; ``` ## DESCRIPTION This class serves as the basis for passive and active objects in ACE. ## Initialization/termination methods. ``` ACE_Task ( ACE_Thread_Manager *thr_mgr = 0, ACE_Message_Queue *mq = 0 ); ``` Initialize a Task, supplying a thread manager and a message queue. If the user doesn't supply a ACE\_Message\_Queue pointer then we'll allocate one dynamically. Otherwise, we'll use the one they give. ``` virtual ~ACE_Task (void); ``` Destructor. ``` ACE_Message_Queue *msg_queue (void); ``` Gets the message queue associated with this task. ``` void msg_queue (ACE_Message_Queue *); ``` Sets the message queue associated with this task. ## Message queue manipulation methods. ## Enqueue and dequeue methods. For the following five method 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). ``` int putq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); ``` Insert message into the message queue. Note that timeout uses *absolute* time rather than *relative* time. ``` int getq (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0); ``` Extract the first message from the queue (blocking). Note that timeout uses *absolute* time rather than *relative* time. ``` int ungetq (ACE_Message_Block *, ACE_Time_Value *timeout = 0); ``` Return a message to the queue. Note that timeout uses *absolute* time rather than *relative* time. ``` int reply (ACE_Message_Block *, ACE_Time_Value *timeout = 0); ``` Turn the message around and send it back down the Stream. Note that timeout uses *absolute* time rather than *relative* time. ``` int put_next (ACE_Message_Block *msg, ACE_Time_Value *timeout = 0); ``` Transfer message to the adjacent ACE\_Task in a ACE\_Stream. Note that timeout uses *absolute* time rather than *relative* time. ``` int can_put (ACE_Message_Block *); ``` Tests whether we can enqueue a message without blocking. ## ACE\_Task utility routines to identify names et al. ``` const ASYS_TCHAR *name (void) const; ``` Return the name of the enclosing Module if there's one associated with the Task, else returns 0. ## Pointers to next ACE\_Task\_Base (if ACE is part of an ACE\_Stream). ``` ACE_Task *next (void); ``` Get next Task pointer. ``` void next (ACE_Task *); ``` Set next Task pointer. ``` ACE_Task *sibling (void); ``` Return the Task's sibling if there's one associated with the Task's Module, else returns 0. ``` ACE_Module *module (void) const; ``` Return the Task's Module if there is one, else returns 0. ``` int flush (u_long flag = ACE_Task_Flags::ACE_FLUSHALL); ``` Flush the queue. Note that if this conflicts with the C++ iostream flush function, just rewrite the iostream function as ::flush. ## Special routines corresponding to certain message types. ``` void water_marks (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds, size_t); ``` Manipulate watermarks. ``` ACE_Message_Queue *msg_queue_; ``` Queue of messages on the ACE\_Task.. ``` int delete_msg_queue_; ``` 1 if should delete Message\_Queue, 0 otherwise. ``` ACE_Module *mod_; ``` Back-pointer to the enclosing module. ``` ACE_Task *next_; ``` Pointer to adjacent ACE\_Task. ``` void dump (void) const; ``` Dump the state of an object. ``` ACE_ALLOC_HOOK_DECLARE; ``` Declare the dynamic allocation hooks. ## Disallow these operations. ``` inline ACE_UNIMPLEMENTED_FUNC ( void operator= (const ACE_Task &) ); ``` ## AUTHOR Doug Schmidt ## LIBRARY ace