## NAME

ACE_Stream - This class is the primary abstraction for the ASX framework. It is moduled after System V Stream.

## SYNOPSIS

    #include <ace/Stream.h>

    template<ACE_SYNCH_DECL>
    class ACE_Stream
    {
      public:
        friend class ACE_Stream_Iterator<ACE_SYNCH_USE>;
        enum{ M_DELETE = 3 };
        ACE_Stream (
            void *arg = 0,
            ACE_Module<ACE_SYNCH_USE> *head = 0,
            ACE_Module<ACE_SYNCH_USE> *tail = 0
            );
        virtual int open (
            void *arg,
            ACE_Module<ACE_SYNCH_USE> *head = 0,
            ACE_Module<ACE_SYNCH_USE> *tail = 0
            );
        virtual int close (int flags = M_DELETE);
        virtual ~ACE_Stream (void);
        virtual int push (ACE_Module<ACE_SYNCH_USE> *mod);
        virtual int pop (int flags = M_DELETE);
        virtual int top (ACE_Module<ACE_SYNCH_USE> *&mod);
        virtual int remove (const ASYS_TCHAR *mod, int flags = M_DELETE);
        virtual ACE_Module<ACE_SYNCH_USE> *head (void);
        virtual ACE_Module<ACE_SYNCH_USE> *tail (void);
        virtual ACE_Module<ACE_SYNCH_USE> *find (const ASYS_TCHAR *mod);
        virtual int link (ACE_Stream<ACE_SYNCH_USE> &);
        virtual int unlink (void);
        virtual int put (
            ACE_Message_Block *mb,
            ACE_Time_Value *timeout = 0
            );
        virtual int get (
            ACE_Message_Block *&mb,
            ACE_Time_Value *timeout = 0
            );
        virtual int control (
            ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds cmd,
            void *args
            );
        virtual int wait (void);
        virtual void dump (void) const;
        ACE_ALLOC_HOOK_DECLARE;
      private:
        int unlink_i (void);
        int link_i (ACE_Stream<ACE_SYNCH_USE> &);
        int push_module (
            ACE_Module<ACE_SYNCH_USE> *,
            ACE_Module<ACE_SYNCH_USE> * = 0,
            ACE_Module<ACE_SYNCH_USE> * = 0
            );
        ACE_Module<ACE_SYNCH_USE> *stream_head_;
        ACE_Module<ACE_SYNCH_USE> *stream_tail_;
        ACE_Stream<ACE_SYNCH_USE> *linked_us_;
        ACE_SYNCH_MUTEX_T lock_;
        ACE_SYNCH_CONDITION_T final_close_;
    };

## DESCRIPTION

A Stream consists of a stack of `ACE_Modules`, each of which contains two `ACE_Tasks`. Even though the methods in this class are virtual, this class isn't really intended for subclassing unless you know what you are doing. In particular, the `ACE_Stream` destructor calls `close`, which won't be overridden properly unless you call it in a subclass destructor.

## Initializatation and termination methods.

    ACE_Stream (
        void *arg = 0,
        ACE_Module<ACE_SYNCH_USE> *head = 0,
        ACE_Module<ACE_SYNCH_USE> *tail = 0
        );

Create a Stream consisting of `head` and `tail` as the Stream head and Stream tail, respectively. If these are 0 then the `ACE_Stream_Head` and `ACE_Stream_Tail` are used, respectively. `arg` is the value past in to the open() methods of the tasks.

    virtual int open (
        void *arg,
        ACE_Module<ACE_SYNCH_USE> *head = 0,
        ACE_Module<ACE_SYNCH_USE> *tail = 0
        );

Create a Stream consisting of `head` and `tail` as the Stream head and Stream tail, respectively. If these are 0 then the `ACE_Stream_Head` and `ACE_Stream_Tail` are used, respectively. `arg` is the value past in to the open() methods of the tasks.

    virtual int close (int flags = M_DELETE);

Close down the stream and release all the resources.

    virtual ~ACE_Stream (void);

Close down the stream and release all the resources.

## ACE_Stream plumbing operations

    virtual int push (ACE_Module<ACE_SYNCH_USE> *mod);

Add a new module `mod` right below the Stream head.

    virtual int pop (int flags = M_DELETE);

Remove the `mod` right below the Stream head and close it down.

    virtual int top (ACE_Module<ACE_SYNCH_USE> *&mod);

Return the top module on the stream (right below the stream head).

    virtual int remove (const ASYS_TCHAR *mod, int flags = M_DELETE);

Remove the named module `mod` from the stream. This bypasses the strict LIFO ordering of push() and pop().

    virtual ACE_Module<ACE_SYNCH_USE> *head (void);

Return current stream head.

    virtual ACE_Module<ACE_SYNCH_USE> *tail (void);

Return current stream tail.

    virtual ACE_Module<ACE_SYNCH_USE> *find (const ASYS_TCHAR *mod);

Find a particular ACE_Module.

    virtual int link (ACE_Stream<ACE_SYNCH_USE> &);

Create a pipe between two Streams.

    virtual int unlink (void);

Remove a pipe formed between two Streams.

## Blocking data transfer operations

    virtual int put (ACE_Message_Block *mb, ACE_Time_Value *timeout = 0);

Send the message `mb` down the stream, starting at the Module below the Stream head. Wait for upto `timeout` amount of time for the operation to complete (or block forever if `timeout` == 0).

    virtual int get (ACE_Message_Block *&mb, ACE_Time_Value *timeout = 0);

Read the message `mb` that is stored in the the stream head. Wait for upto `timeout` amount of time for the operation to complete (or block forever if `timeout` == 0).

    virtual int control (
        ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds cmd,
        void *args
        );

Send control message down the stream.

    virtual int wait (void);

Synchronize with the final close of the stream.

    virtual void dump (void) const;

Dump the state of an object.

    ACE_ALLOC_HOOK_DECLARE;

Declare the dynamic allocation hooks.

## Synchronization objects used for thread-safe streams.

    ACE_SYNCH_MUTEX_T lock_;

Protect the stream against race conditions.

    ACE_SYNCH_CONDITION_T final_close_;

Use to tell all threads waiting on the close that we are done.

## AUTHOR

Doug Schmidt

## LIBRARY

ace