dep/ACE_wrappers/ace/Stream.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Stream.h
   6  *
   7  *  $Id: Stream.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Douglas C. Schmidt <schmidt@uci.edu>
  10  */
  11 //==========================================================================
  12
  13 #ifndef ACE_STREAM_H
  14 #define ACE_STREAM_H
  15
  16 #include /**/ "ace/pre.h"
  17
  18 #include /**/ "ace/config-all.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/IO_Cntl_Msg.h"
  25 #include "ace/Message_Block.h"
  26 #include "ace/Module.h"
  27
  28 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  29
  30 // Forward decls.
  31 template<ACE_SYNCH_DECL> class ACE_Stream_Iterator;
  32 class ACE_Time_Value;
  33
  34 /**
  35  * @class ACE_Stream
  36  *
  37  * @brief This class is the primary abstraction for the ASX framework.
  38  * It is moduled after System V Stream.
  39  *
  40  * A Stream consists of a stack of <ACE_Modules>, each of which
  41  * contains two <ACE_Tasks>.  Even though the methods in this
  42  * class are virtual, this class isn't really intended for
  43  * subclassing unless you know what you are doing.  In
  44  * particular, the ACE_Stream destructor calls <close>, which
  45  * won't be overridden properly unless you call it in a subclass
  46  * destructor.
  47  */
  48 template <ACE_SYNCH_DECL>
  49 class ACE_Stream
  50 {
  51 public:
  52   friend class ACE_Stream_Iterator<ACE_SYNCH_USE>;
  53
  54   enum
  55   {
  56     /// Indicates that <close> deletes the Tasks.  Don't change this
  57     /// value without updating the same enum in class ACE_Module...
  58     M_DELETE = 3
  59   };
  60
  61   // = Initializatation and termination methods.
  62   /**
  63    * Create a Stream consisting of <head> and <tail> as the Stream
  64    * head and Stream tail, respectively.  If these are 0 then the
  65    * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively.
  66    * <arg> is the value past in to the <open> methods of the tasks.
  67    */
  68   ACE_Stream (void *arg = 0,
  69               ACE_Module<ACE_SYNCH_USE> *head = 0,
  70               ACE_Module<ACE_SYNCH_USE> *tail = 0);
  71
  72   /**
  73    * Create a Stream consisting of <head> and <tail> as the Stream
  74    * head and Stream tail, respectively.  If these are 0 then the
  75    * <ACE_Stream_Head> and <ACE_Stream_Tail> are used, respectively.
  76    * <arg> is the value past in to the <open> methods of the tasks.
  77    */
  78   virtual int open (void *arg,
  79                     ACE_Module<ACE_SYNCH_USE> *head = 0,
  80                     ACE_Module<ACE_SYNCH_USE> *tail = 0);
  81
  82   /// Close down the stream and release all the resources.
  83   virtual int close (int flags = M_DELETE);
  84
  85   /// Close down the stream and release all the resources.
  86   virtual ~ACE_Stream (void);
  87
  88   // = ACE_Stream plumbing operations
  89
  90   /// Add a new module <mod> right below the Stream head.  The
  91   /// <open()> hook methods of the <ACE_Tasks> in this ACE_Module
  92   /// are invoked to initialize the tasks.
  93   virtual int push (ACE_Module<ACE_SYNCH_USE> *mod);
  94
  95   /// Remove the <mod> right below the Stream head and close it down.
  96   //  The <close()> hook methods of the <ACE_Tasks> in this ACE_Module
  97   /// are invoked to cleanup the tasks.
  98   virtual int pop (int flags = M_DELETE);
  99
 100   /// Return the top module on the stream (right below the stream
 101   /// head).
 102   virtual int top (ACE_Module<ACE_SYNCH_USE> *&mod);
 103
 104   /// Insert a new module <mod> below the named module <prev_name>.
 105   virtual int insert (const ACE_TCHAR *prev_name,
 106                       ACE_Module<ACE_SYNCH_USE> *mod);
 107
 108   /// Replace the named module <replace_name> with a new module <mod>.
 109   virtual int replace (const ACE_TCHAR *replace_name,
 110                        ACE_Module<ACE_SYNCH_USE> *mod,
 111                        int flags = M_DELETE);
 112
 113   /// Remove the named module <mod> from the stream.  This bypasses the
 114   /// strict LIFO ordering of <push> and <pop>.
 115   virtual int remove (const ACE_TCHAR *mod,
 116                       int flags = M_DELETE);
 117
 118   /// Return current stream head.
 119   virtual ACE_Module<ACE_SYNCH_USE> *head (void);
 120
 121   /// Return current stream tail.
 122   virtual ACE_Module<ACE_SYNCH_USE> *tail (void);
 123
 124   /// Find a particular ACE_Module.
 125   virtual ACE_Module<ACE_SYNCH_USE> *find (const ACE_TCHAR *mod);
 126
 127   /// Create a pipe between two Streams.
 128   virtual int link (ACE_Stream<ACE_SYNCH_USE> &);
 129
 130   /// Remove a pipe formed between two Streams.
 131   virtual int unlink (void);
 132
 133   // = Blocking data transfer operations
 134   /**
 135    * Send the message @a mb down the stream, starting at the Module
 136    * below the Stream head.  Wait for upto @a timeout amount of
 137    * absolute time for the operation to complete (or block forever if
 138    * @a timeout == 0).
 139    */
 140   virtual int put (ACE_Message_Block *mb,
 141                    ACE_Time_Value *timeout = 0);
 142
 143   /**
 144    * Read the message @a mb that is stored in the stream head.
 145    * Wait for upto @a timeout amount of absolute time for the operation
 146    * to complete (or block forever if @a timeout == 0).
 147    */
 148   virtual int get (ACE_Message_Block *&mb,
 149                    ACE_Time_Value *timeout = 0);
 150
 151   /// Send control message down the stream.
 152   virtual int control (ACE_IO_Cntl_Msg::ACE_IO_Cntl_Cmds cmd,
 153                        void *args);
 154
 155   /// Synchronize with the final close of the stream.
 156   virtual int wait (void);
 157
 158   /// Dump the state of an object.
 159   virtual void dump (void) const;
 160
 161   /// Declare the dynamic allocation hooks.
 162   ACE_ALLOC_HOOK_DECLARE;
 163
 164 private:
 165   /// Actually perform the unlinking of two Streams (must be called
 166   /// with locks held).
 167   int unlink_i (void);
 168
 169   /// Actually perform the linking of two Streams (must be called with
 170   /// locks held).
 171   int link_i (ACE_Stream<ACE_SYNCH_USE> &);
 172
 173   /// Must a new module onto the Stream.
 174   int push_module (ACE_Module<ACE_SYNCH_USE> *,
 175                    ACE_Module<ACE_SYNCH_USE> * = 0,
 176                    ACE_Module<ACE_SYNCH_USE> * = 0);
 177
 178   /// Pointer to the head of the stream.
 179   ACE_Module<ACE_SYNCH_USE> *stream_head_;
 180
 181   /// Pointer to the tail of the stream.
 182   ACE_Module<ACE_SYNCH_USE> *stream_tail_;
 183
 184   /// Pointer to an adjoining linked stream.
 185   ACE_Stream<ACE_SYNCH_USE> *linked_us_;
 186
 187   // = Synchronization objects used for thread-safe streams.
 188   /// Protect the stream against race conditions.
 189   ACE_SYNCH_MUTEX_T lock_;
 190
 191   /// Use to tell all threads waiting on the close that we are done.
 192   ACE_SYNCH_CONDITION_T final_close_;
 193 };
 194
 195 /**
 196  * @class ACE_Stream_Iterator
 197  *
 198  * @brief Iterate through an ACE_Stream.
 199  */
 200 template <ACE_SYNCH_DECL>
 201 class ACE_Stream_Iterator
 202 {
 203 public:
 204   // = Initialization method.
 205   ACE_Stream_Iterator (const ACE_Stream<ACE_SYNCH_USE> &sr);
 206
 207   // = Iteration methods.
 208
 209   /// Pass back the <next_item> that hasn't been seen in the set.
 210   /// Returns 0 when all items have been seen, else 1.
 211   int next (const ACE_Module<ACE_SYNCH_USE> *&next_item);
 212
 213   /// Returns 1 when all items have been seen, else 0.
 214   int done (void) const;
 215
 216   /// Move forward by one element in the set.  Returns 0 when all the
 217   /// items in the set have been seen, else 1.
 218   int advance (void);
 219
 220 private:
 221   /// Next <Module> that we haven't yet seen.
 222   ACE_Module<ACE_SYNCH_USE> *next_;
 223 };
 224
 225 ACE_END_VERSIONED_NAMESPACE_DECL
 226
 227 #if defined (__ACE_INLINE__)
 228 #include "ace/Stream.inl"
 229 #endif /* __ACE_INLINE__ */
 230
 231 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
 232 #include "ace/Stream.cpp"
 233 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
 234
 235 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
 236 #pragma implementation ("Stream.cpp")
 237 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
 238
 239 #include /**/ "ace/post.h"
 240
 241 #endif /* ACE_STREAM_H */