--- name: "ACE_Stream" 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_Stream" --- # ACE\_Stream(3) This class is the primary abstraction for the ASX framework. It is moduled after System V Stream. ## NAME ACE\_Stream - This class is the primary abstraction for the ASX framework. It is moduled after System V Stream. ## SYNOPSIS ``` #include template class ACE_Stream { public: friend class ACE_Stream_Iterator; enum{ M_DELETE = 3 }; ACE_Stream ( void *arg = 0, ACE_Module *head = 0, ACE_Module *tail = 0 ); virtual int open ( void *arg, ACE_Module *head = 0, ACE_Module *tail = 0 ); virtual int close (int flags = M_DELETE); virtual ~ACE_Stream (void); virtual int push (ACE_Module *mod); virtual int pop (int flags = M_DELETE); virtual int top (ACE_Module *&mod); virtual int remove (const ASYS_TCHAR *mod, int flags = M_DELETE); virtual ACE_Module *head (void); virtual ACE_Module *tail (void); virtual ACE_Module *find (const ASYS_TCHAR *mod); virtual int link (ACE_Stream &); 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 &); int push_module ( ACE_Module *, ACE_Module * = 0, ACE_Module * = 0 ); ACE_Module *stream_head_; ACE_Module *stream_tail_; ACE_Stream *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 *head = 0, ACE_Module *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 *head = 0, ACE_Module *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 *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 *&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 *head (void); ``` Return current stream head. ``` virtual ACE_Module *tail (void); ``` Return current stream tail. ``` virtual ACE_Module *find (const ASYS_TCHAR *mod); ``` Find a particular ACE\_Module. ``` virtual int link (ACE_Stream &); ``` 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