Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Stream.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    Stream.h
00006  *
00007  *  $Id: Stream.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@uci.edu>
00010  */
00011 //==========================================================================
00012 
00013 #ifndef ACE_STREAM_H
00014 #define ACE_STREAM_H
00015 
00016 #include "ace/pre.h"
00017 
00018 #include "ace/config-all.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 #include "ace/IO_Cntl_Msg.h"
00025 #include "ace/Message_Block.h"
00026 #include "ace/Time_Value.h"
00027 #include "ace/Module.h"
00028 
00029 // Forward decls.
00030 template<ACE_SYNCH_DECL> class ACE_Stream_Iterator;
00031 
00032 /**
00033  * @class ACE_Stream
00034  *
00035  * @brief This class is the primary abstraction for the ASX framework.
00036  * It is moduled after System V Stream.
00037  *
00038  * A Stream consists of a stack of <ACE_Modules>, each of which
00039  * contains two <ACE_Tasks>.  Even though the methods in this
00040  * class are virtual, this class isn't really intended for
00041  * subclassing unless you know what you are doing.  In
00042  * particular, the <ACE_Stream> destructor calls <close>, which
00043  * won't be overridden properly unless you call it in a subclass
00044  * destructor.
00045  */
00046 template <ACE_SYNCH_DECL>
00047 class ACE_Stream
00048 {
00049 public:
00050   friend class ACE_Stream_Iterator<ACE_SYNCH_USE>;
00051 
00052   enum
00053   {
00054     /// Indicates that <close> deletes the Tasks.  Don't change this
00055     /// value without updating the same enum in class ACE_Module...
00056     M_DELETE = 3
00057   };
00058 
00059   // = Initializatation and termination methods.
00060   /**
00061    * Create a Stream consisting of <head> and <tail> as the Stream
00062    * head and Stream tail, respectively.  If these are 0 then the
00063    * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively.
00064    * <arg> is the value past in to the <open> methods of the tasks.
00065    */
00066   ACE_Stream (void *arg = 0,
00067               ACE_Module<ACE_SYNCH_USE> *head = 0,
00068               ACE_Module<ACE_SYNCH_USE> *tail = 0);
00069 
00070   /**
00071    * Create a Stream consisting of <head> and <tail> as the Stream
00072    * head and Stream tail, respectively.  If these are 0 then the
00073    * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively.
00074    * <arg> is the value past in to the <open> methods of the tasks.
00075    */
00076   virtual int open (void *arg,
00077                     ACE_Module<ACE_SYNCH_USE> *head = 0,
00078                     ACE_Module<ACE_SYNCH_USE> *tail = 0);
00079 
00080   /// Close down the stream and release all the resources.
00081   virtual int close (int flags = M_DELETE);
00082 
00083   /// Close down the stream and release all the resources.
00084   virtual ~ACE_Stream (void);
00085 
00086   // = ACE_Stream plumbing operations
00087 
00088   /// Add a new module <mod> right below the Stream head.
00089   virtual int push (ACE_Module<ACE_SYNCH_USE> *mod);
00090 
00091   /// Remove the <mod> right below the Stream head and close it down.
00092   virtual int pop (int flags = M_DELETE);
00093 
00094   /// Return the top module on the stream (right below the stream
00095   /// head).
00096   virtual int top (ACE_Module<ACE_SYNCH_USE> *&mod);
00097 
00098   /// Insert a new module <mod> below the named module <prev_name>.
00099   virtual int insert (const ACE_TCHAR *prev_name,
00100                       ACE_Module<ACE_SYNCH_USE> *mod);
00101 
00102   /// Replace the named module <replace_name> with a new module <mod>.
00103   virtual int replace (const ACE_TCHAR *replace_name,
00104                        ACE_Module<ACE_SYNCH_USE> *mod,
00105                        int flags = M_DELETE);
00106 
00107   /// Remove the named module <mod> from the stream.  This bypasses the
00108   /// strict LIFO ordering of <push> and <pop>.
00109   virtual int remove (const ACE_TCHAR *mod,
00110                       int flags = M_DELETE);
00111 
00112   /// Return current stream head.
00113   virtual ACE_Module<ACE_SYNCH_USE> *head (void);
00114 
00115   /// Return current stream tail.
00116   virtual ACE_Module<ACE_SYNCH_USE> *tail (void);
00117 
00118   /// Find a particular ACE_Module.
00119   virtual ACE_Module<ACE_SYNCH_USE> *find (const ACE_TCHAR *mod);
00120 
00121   /// Create a pipe between two Streams.
00122   virtual int link (ACE_Stream<ACE_SYNCH_USE> &);
00123 
00124   /// Remove a pipe formed between two Streams.
00125   virtual int unlink (void);
00126 
00127   // = Blocking data transfer operations
00128   /**
00129    * Send the message <mb> down the stream, starting at the Module
00130    * below the Stream head.  Wait for upto <timeout> amount of
00131    * absolute time for the operation to complete (or block forever if
00132    * <timeout> == 0).
00133    */
00134   virtual int put (ACE_Message_Block *mb,
00135                    ACE_Time_Value *timeout = 0);
00136 
00137   /**
00138    * Read the message <mb> that is stored in the stream head.
00139    * Wait for upto <timeout> amount of absolute time for the operation
00140    * to complete (or block forever if <timeout> == 0).
00141    */
00142   virtual int get (ACE_Message_Block *&mb,
00143                    ACE_Time_Value *timeout = 0);
00144 
00145   /// Send control message down the stream.
00146   virtual int control (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds cmd,
00147                        void *args);
00148 
00149   /// Synchronize with the final close of the stream.
00150   virtual int wait (void);
00151 
00152   /// Dump the state of an object.
00153   virtual void dump (void) const;
00154 
00155   /// Declare the dynamic allocation hooks.
00156   ACE_ALLOC_HOOK_DECLARE;
00157 
00158 private:
00159   /// Actually perform the unlinking of two Streams (must be called
00160   /// with locks held).
00161   int unlink_i (void);
00162 
00163   /// Actually perform the linking of two Streams (must be called with
00164   /// locks held).
00165   int link_i (ACE_Stream<ACE_SYNCH_USE> &);
00166 
00167   /// Must a new module onto the Stream.
00168   int push_module (ACE_Module<ACE_SYNCH_USE> *,
00169                    ACE_Module<ACE_SYNCH_USE> * = 0,
00170                    ACE_Module<ACE_SYNCH_USE> * = 0);
00171 
00172   /// Pointer to the head of the stream.
00173   ACE_Module<ACE_SYNCH_USE> *stream_head_;
00174 
00175   /// Pointer to the tail of the stream.
00176   ACE_Module<ACE_SYNCH_USE> *stream_tail_;
00177 
00178   /// Pointer to an adjoining linked stream.
00179   ACE_Stream<ACE_SYNCH_USE> *linked_us_;
00180 
00181   // = Synchronization objects used for thread-safe streams.
00182   /// Protect the stream against race conditions.
00183   ACE_SYNCH_MUTEX_T lock_;
00184 
00185   /// Use to tell all threads waiting on the close that we are done.
00186   ACE_SYNCH_CONDITION_T final_close_;
00187 };
00188 
00189 /**
00190  * @class ACE_Stream_Iterator
00191  *
00192  * @brief Iterate through an <ACE_Stream>.
00193  */
00194 template <ACE_SYNCH_DECL>
00195 class ACE_Stream_Iterator
00196 {
00197 public:
00198   // = Initialization method.
00199   ACE_Stream_Iterator (const ACE_Stream<ACE_SYNCH_USE> &sr);
00200 
00201   // = Iteration methods.
00202 
00203   /// Pass back the <next_item> that hasn't been seen in the set.
00204   /// Returns 0 when all items have been seen, else 1.
00205   int next (const ACE_Module<ACE_SYNCH_USE> *&next_item);
00206 
00207   /// Returns 1 when all items have been seen, else 0.
00208   int done (void) const;
00209 
00210   /// Move forward by one element in the set.  Returns 0 when all the
00211   /// items in the set have been seen, else 1.
00212   int advance (void);
00213 
00214 private:
00215   /// Next <Module> that we haven't yet seen.
00216   ACE_Module<ACE_SYNCH_USE> *next_;
00217 };
00218 
00219 #if defined (__ACE_INLINE__)
00220 #include "ace/Stream.i"
00221 #endif /* __ACE_INLINE__ */
00222 
00223 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00224 #include "ace/Stream.cpp"
00225 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00226 
00227 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00228 #pragma implementation ("Stream.cpp")
00229 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00230 
00231 #include "ace/post.h"
00232 
00233 #endif /* ACE_STREAM_H */

Generated on Mon Jun 16 11:21:29 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002