## NAME

ACE_Task - Primary interface for application message processing, as well as input and output message queueing.

## SYNOPSIS

    #include <ace/Task_T.h>

    template<ACE_SYNCH_DECL>
    class ACE_Task : public ACE_Task_Base
    {
      public:
        friend class ACE_Module<ACE_SYNCH_USE>;
        friend class ACE_Module_Type;
        ACE_Task (
            ACE_Thread_Manager *thr_mgr = 0,
            ACE_Message_Queue<ACE_SYNCH_USE> *mq = 0
            );
        virtual ~ACE_Task (void);
        ACE_Message_Queue<ACE_SYNCH_USE> *msg_queue (void);
        void msg_queue (ACE_Message_Queue<ACE_SYNCH_USE> *);
        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<ACE_SYNCH_USE> *next (void);
        void next (ACE_Task<ACE_SYNCH_USE> *);
        ACE_Task<ACE_SYNCH_USE> *sibling (void);
        ACE_Module<ACE_SYNCH_USE> *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<ACE_SYNCH_USE> *msg_queue_;
        int delete_msg_queue_;
        ACE_Module<ACE_SYNCH_USE> *mod_;
        ACE_Task<ACE_SYNCH_USE> *next_;
        void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      private:
        inline ACE_UNIMPLEMENTED_FUNC (
            void operator= (const ACE_Task<ACE_SYNCH_USE> &)
            );
    };

## 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<ACE_SYNCH_USE> *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<ACE_SYNCH_USE> *msg_queue (void);

Gets the message queue associated with this task.

    void msg_queue (ACE_Message_Queue<ACE_SYNCH_USE> *);

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<ACE_SYNCH_USE> *next (void);

Get next Task pointer.

    void next (ACE_Task<ACE_SYNCH_USE> *);

Set next Task pointer.

    ACE_Task<ACE_SYNCH_USE> *sibling (void);

Return the Task's sibling if there's one associated with the Task's Module, else returns 0.

    ACE_Module<ACE_SYNCH_USE> *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<ACE_SYNCH_USE> *msg_queue_;

Queue of messages on the ACE_Task..

    int delete_msg_queue_;

1 if should delete Message_Queue, 0 otherwise.

    ACE_Module<ACE_SYNCH_USE> *mod_;

Back-pointer to the enclosing module.

    ACE_Task<ACE_SYNCH_USE> *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<ACE_SYNCH_USE> &)
        );

## AUTHOR

Doug Schmidt

## LIBRARY

ace