ACE/ace/IOStream.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    IOStream.h
   6  *
   7  *  @author James CE Johnson <jcej@lads.com>
   8  *  @author Jim Crossley <jim@lads.com>
   9  */
  10 //=============================================================================
  11
  12 #ifndef ACE_IOSTREAM_H
  13 #define ACE_IOSTREAM_H
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 // Needed on Windows for streambuf
  23 // FUZZ: disable check_for_streams_include
  24 #include "ace/streams.h"
  25
  26 // This is a temporary restriction - ACE_IOStream is only enabled if the
  27 // compiler does not supply the standard C++ library (and standard iostreams)
  28 // or, if it does, the platform is explicitly set to use old iostreams
  29 // by its config.h file.
  30 // This restriction is recorded in Bugzilla entry 857.
  31 #if !defined (ACE_USES_OLD_IOSTREAMS) && !defined (ACE_LACKS_ACE_IOSTREAM)
  32 #  define ACE_LACKS_ACE_IOSTREAM
  33 #endif /* !ACE_USES_OLD_IOSTREAMS && !ACE_LACKS_ACE_IOSTREAM */
  34
  35 #if !defined (ACE_LACKS_ACE_IOSTREAM)
  36
  37 # include /**/ <string>
  38
  39 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  40 typedef std::string ACE_IOStream_String;
  41 ACE_END_VERSIONED_NAMESPACE_DECL
  42
  43 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  44
  45 class ACE_Export ACE_Quoted_String : public ACE_IOStream_String
  46 {
  47 public:
  48   inline ACE_Quoted_String () { *this = ""; }
  49   inline ACE_Quoted_String (const char *c) { *this = ACE_IOStream_String (c); }
  50   inline ACE_Quoted_String (const ACE_IOStream_String &s) { *this = s; }
  51   inline ACE_Quoted_String &operator= (const ACE_IOStream_String& s)
  52   {
  53     return (ACE_Quoted_String &) ACE_IOStream_String::operator= (s);
  54   }
  55   inline ACE_Quoted_String &operator = (const char c) {
  56     return (ACE_Quoted_String &) ACE_IOStream_String::operator= (c);
  57   }
  58   inline ACE_Quoted_String &operator = (const char *c) {
  59     return (ACE_Quoted_String &) ACE_IOStream_String::operator= (c);
  60   }
  61   inline bool operator < (const ACE_Quoted_String &s) const {
  62     return *(ACE_IOStream_String *) this < (ACE_IOStream_String) s;
  63   }
  64 #    if defined (ACE_WIN32) && defined (_MSC_VER)
  65   inline int length () { return this->GetLength (); }
  66 #    endif /* ACE_WIN32 && defined (_MSC_VER) */
  67 };
  68
  69 ACE_END_VERSIONED_NAMESPACE_DECL
  70
  71 # include "ace/Time_Value.h"
  72 # include "ace/os_include/sys/os_types.h"
  73
  74 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  75
  76 /**
  77  * @class ACE_Streambuf
  78  *
  79  * @brief Create your custom streambuf by providing and ACE_*_Stream
  80  * object to this template.  I have tested it with
  81  * ACE_SOCK_Stream and it should work fine for others as well.
  82  *
  83  * For any iostream object, the real work is done by the
  84  * underlying streambuf class.  That is what we create here.
  85  * A streambuf has an internal buffer area into which data is
  86  * read and written as the iostream requests and provides data.
  87  * At some point during the read process, the iostream will
  88  * realize that the streambuf has no more data.  The underflow
  89  * function of the streambuf is then called.
  90  * Likewise, during the write process, the iostream will
  91  * eventually notice that the streabuf's buffer has become full
  92  * and will invoke the overflow function.
  93  * The empty/full state of the read/write "buffers" are
  94  * controled by two sets pointers.  One set is dedicated to
  95  * read, the other to write.  These pointers, in turn, reference
  96  * a common buffer that is to be shared by both read and write
  97  * operations.  It is this common buffer to which data is
  98  * written and from which it is read.
  99  * The common buffer is used by functions of the streambuf as
 100  * well as the iostream.  Because of this and the fact that it
 101  * is "shared" by both read and write operators, there is a
 102  * danger of data corruption if read and write operations are
 103  * allowed to take place "at the same time".
 104  * To prevent data corruption, we manipulate the read and write
 105  * pointer sets so that the streambuf is in either a read-mode
 106  * or write-mode at all times and can never be in both modes at
 107  * the same time.
 108  * In the constructor: set the read and write sets to NULL This
 109  * causes the underflow or overflow operators to be invoked at
 110  * the first IO activity of the iostream.
 111  * In the underflow function we arrange for the common buffer to
 112  * reference our read buffer and for the write pointer set to be
 113  * disabled.  If a write operation is performed by the iostream
 114  * this will cause the overflow function to be invoked.
 115  * In the overflow function we arrange for the common buffer to
 116  * reference our write buffer and for the read pointer set to be
 117  * disabled.  This causes the underflow function to be invoked
 118  * when the iostream "changes our mode".
 119  * The overflow function will also invoke the send_n function to
 120  * flush the buffered data to our peer.  Similarly, the sync and
 121  * syncout functions will cause send_n to be invoked to send the
 122  * data.
 123  * Since socket's and the like do not support seeking, there can
 124  * be no method for "syncing" the input.  However, since we
 125  * maintain separate read/write buffers, no data is lost by
 126  * "syncing" the input.  It simply remains buffered.
 127  */
 128 class ACE_Export ACE_Streambuf : public streambuf
 129 {
 130 public:
 131   /**
 132    * If the default allocation strategy were used the common buffer
 133    * would be deleted when the object destructs.  Since we are
 134    * providing separate read/write buffers, it is up to us to manage
 135    * their memory.
 136    */
 137   virtual ~ACE_Streambuf ();
 138
 139   /// Get the current Time_Value pointer and provide a new one.
 140   ACE_Time_Value *recv_timeout (ACE_Time_Value *tv = 0);
 141
 142   /**
 143    * Use this to allocate a new/different buffer for put operations.
 144    * If you do not provide a buffer pointer, one will be allocated.
 145    * That is the preferred method.  If you do provide a buffer, the
 146    * size must match that being used by the get buffer.  If
 147    * successful, you will receive a pointer to the current put buffer.
 148    * It is your responsibility to delete this memory when you are done
 149    * with it.
 150    */
 151   char *reset_put_buffer (char *newBuffer = 0,
 152                           u_int _streambuf_size = 0,
 153                           u_int _pptr = 0 );
 154
 155   /// Return the number of bytes to be 'put' onto the stream media.
 156   ///    pbase + put_avail = pptr
 157   u_int put_avail ();
 158
 159   /**
 160    * Use this to allocate a new/different buffer for get operations.
 161    * If you do not provide a buffer pointer, one will be allocated.
 162    * That is the preferred method.  If you do provide a buffer, the
 163    * size must match that being used by the put buffer.  If
 164    * successful, you will receive a pointer to the current get buffer.
 165    * It is your responsibility to delete this memory when you are done
 166    * with it.
 167    */
 168   char *reset_get_buffer (char *newBuffer = 0,
 169                           u_int _streambuf_size = 0,
 170                           u_int _gptr = 0,
 171                           u_int _egptr = 0);
 172
 173   /// Return the number of bytes not yet gotten.  eback + get_waiting =
 174   /// gptr
 175   u_int get_waiting ();
 176
 177   /// Return the number of bytes in the get area (includes some already
 178   /// gotten); eback + get_avail = egptr
 179   u_int get_avail ();
 180
 181   /// Query the streambuf for the size of its buffers.
 182   u_int streambuf_size ();
 183
 184   /// Did we take an error because of an IO operation timeout?
 185   /// @note Invoking this resets the flag.
 186   u_char timeout ();
 187
 188 protected:
 189   ACE_Streambuf (u_int streambuf_size,
 190                  int io_mode);
 191
 192   /// Sync both input and output. See syncin/syncout below for
 193   /// descriptions.
 194   virtual int sync ();
 195
 196   // = Signatures for the underflow/overflow discussed above.
 197   virtual int underflow ();
 198
 199   /// The overflow function receives the character which caused the
 200   /// overflow.
 201   virtual int overflow (int c = EOF);
 202
 203   /// Resets the <base> pointer and streambuf mode.  This is used
 204   /// internally when get/put buffers are allocatd.
 205   void reset_base ();
 206
 207 protected:
 208   // = Two pointer sets for manipulating the read/write areas.
 209   char *eback_saved_;
 210   char *gptr_saved_;
 211   char *egptr_saved_;
 212   char *pbase_saved_;
 213   char *pptr_saved_;
 214   char *epptr_saved_;
 215
 216   // = With cur_mode_ we keep track of our current IO mode.
 217
 218   // This helps us to optimize the underflow/overflow functions.
 219   u_char cur_mode_;
 220   const u_char get_mode_;
 221   const u_char put_mode_;
 222
 223   /// mode tells us if we're working for an istream, ostream, or
 224   /// iostream.
 225   int mode_;
 226
 227   /// This defines the size of the input and output buffers.  It can be
 228   /// set by the object constructor.
 229   const u_int streambuf_size_;
 230
 231   /// Did we take an error because of an IO operation timeout?
 232   u_char timeout_;
 233
 234   /// We want to allow the user to provide Time_Value pointers to
 235   /// prevent infinite blocking while waiting to receive data.
 236   ACE_Time_Value recv_timeout_value_;
 237   ACE_Time_Value *recv_timeout_;
 238
 239   /**
 240    * syncin is called when the input needs to be synced with the
 241    * source file.  In a filebuf, this results in the <seek> system
 242    * call being used.  We can't do that on socket-like connections, so
 243    * this does basically nothing.  That's safe because we have a
 244    * separate read buffer to maintain the already-read data.  In a
 245    * filebuf, the single common buffer is used forcing the <seek>
 246    * call.
 247    */
 248   int syncin ();
 249
 250   /// syncout() is called when the output needs to be flushed.  This is
 251   /// easily done by calling the peer's send_n function.
 252   int syncout ();
 253
 254   /// flushbuf() is the worker of syncout.  It is a separate function
 255   /// because it gets used sometimes in different context.
 256   int flushbuf ();
 257
 258   /**
 259    * fillbuf is called in a couple of places.  This is the worker of
 260    * underflow.  It will attempt to fill the read buffer from the
 261    * peer.
 262    */
 263   int fillbuf ();
 264
 265   /**
 266    * Used by fillbuf and others to get exactly one byte from the peer.
 267    * recv_n is used to be sure we block until something is available.
 268    * It is virtual because we really need to override it for
 269    * datagram-derived objects.
 270    */
 271   virtual int get_one_byte ();
 272
 273   /**
 274    * Stream connections and "unconnected connections" (ie --
 275    * datagrams) need to work just a little differently.  We derive
 276    * custom Streambuf objects for them and provide these functions at
 277    * that time.
 278    */
 279   virtual ssize_t send (char *buf,
 280                         ssize_t len) = 0;
 281   virtual ssize_t recv (char *buf,
 282                         ssize_t len,
 283                         ACE_Time_Value *tv = 0) = 0;
 284   virtual ssize_t recv (char *buf,
 285                         ssize_t len,
 286                         int flags,
 287                         ACE_Time_Value *tv = 0) = 0;
 288   virtual ssize_t recv_n (char *buf,
 289                           ssize_t len,
 290                           int flags = 0,
 291                           ACE_Time_Value *tv = 0) = 0;
 292
 293   virtual ACE_HANDLE get_handle ();
 294
 295 #  if !defined (ACE_USES_OLD_IOSTREAMS)
 296   char *base () const
 297     {
 298       return cur_mode_ == get_mode_ ? eback_saved_
 299         : cur_mode_ == put_mode_ ? pbase_saved_
 300         : 0;
 301     }
 302   char *ebuf () const
 303     {
 304       return cur_mode_ == 0 ? 0 : base () + streambuf_size_;
 305     }
 306
 307   int blen () const
 308     {
 309       return streambuf_size_;
 310     }
 311
 312   void setb (char* b, char* eb, int /* a */=0)
 313     {
 314       setbuf (b, (eb - b));
 315     }
 316
 317   int out_waiting ()
 318     {
 319       return pptr () - pbase ();
 320     }
 321 #  endif /* !ACE_USES_OLD_IOSTREAMS */
 322 };
 323
 324 ACE_END_VERSIONED_NAMESPACE_DECL
 325
 326 ///////////////////////////////////////////////////////////////////////////
 327
 328 // These typedefs are provided by G++ (on some systems?) without the
 329 // trailing '_'.  Since we can't count on 'em, I've defined them to
 330 // what GNU wants here.
 331 //
 332 typedef ios& (*__manip_)(ios&);
 333 typedef istream& (*__imanip_)(istream&);
 334 typedef ostream& (*__omanip_)(ostream&);
 335
 336 // Trying to do something like is shown below instead of using the
 337 // __*manip typedefs causes Linux do segfault when "<<endl" is done.
 338 //
 339 //        virtual MT& operator<<(ios& (*func)(ios&))  { (*func)(*this); return *this; }
 340
 341 // This macro defines the get operator for class MT into datatype DT.
 342 // We will use it below to quickly override most (all?)  iostream get
 343 // operators.  Notice how the <ipfx> and <isfx> functions are used.
 344
 345 #define GET_SIG(MT,DT)          inline virtual MT& operator>> (DT v)
 346 #define GET_CODE {                      \
 347         if (ipfx (0))                                   \
 348         {                                               \
 349                 iostream::operator>> (v);               \
 350         }                                               \
 351         isfx ();                                        \
 352         return *this;                                   \
 353         }
 354 #define GET_PROT(MT,DT,CODE)    GET_SIG(MT,DT)  CODE
 355 #define GET_FUNC(MT,DT)         GET_PROT(MT,DT,GET_CODE)
 356
 357 // This macro defines the put operator for class MT into datatype DT.
 358 // We will use it below to quickly override most (all?)  iostream put
 359 // operators.  Notice how the <opfx> and <osfx> functions are used.
 360
 361 #define PUT_SIG(MT,DT)          inline virtual MT& operator<< (DT v)
 362 #define PUT_CODE {                      \
 363         if (opfx ())                                    \
 364         {                                               \
 365                 iostream::operator<< (v);               \
 366         }                                               \
 367         osfx ();                                        \
 368         return *this;                                   \
 369         }
 370 #define PUT_PROT(MT,DT,CODE)    PUT_SIG(MT,DT)  CODE
 371 #define PUT_FUNC(MT,DT)         PUT_PROT(MT,DT,PUT_CODE)
 372
 373 // These are necessary in case somebody wants to derive from us and
 374 // override one of these with a custom approach.
 375
 376 #define GET_FUNC_SET0(MT,CODE,CODE2) \
 377         GET_PROT(MT,short &,CODE) \
 378         GET_PROT(MT,u_short &,CODE) \
 379         GET_PROT(MT,int &,CODE) \
 380         GET_PROT(MT,u_int &,CODE) \
 381         GET_PROT(MT,long &,CODE) \
 382         GET_PROT(MT,u_long &,CODE) \
 383         GET_PROT(MT,float &,CODE) \
 384         GET_PROT(MT,double &,CODE) \
 385         GET_PROT(MT,char &,CODE) \
 386         GET_PROT(MT,u_char &,CODE) \
 387         GET_PROT(MT,char *,CODE) \
 388         GET_PROT(MT,u_char *,CODE) \
 389         inline virtual MT& operator>>(__omanip_ func) CODE2 \
 390         inline virtual MT& operator>>(__manip_ func)  CODE2
 391
 392 #define PUT_FUNC_SET0(MT,CODE,CODE2) \
 393         PUT_PROT(MT,short,CODE) \
 394         PUT_PROT(MT,u_short,CODE) \
 395         PUT_PROT(MT,int,CODE) \
 396         PUT_PROT(MT,u_int,CODE) \
 397         PUT_PROT(MT,long,CODE) \
 398         PUT_PROT(MT,u_long,CODE) \
 399         PUT_PROT(MT,float,CODE) \
 400         PUT_PROT(MT,double,CODE) \
 401         PUT_PROT(MT,char,CODE) \
 402         PUT_PROT(MT,u_char,CODE) \
 403         PUT_PROT(MT,const char *,CODE) \
 404         PUT_PROT(MT,u_char *,CODE) \
 405         PUT_PROT(MT,void *,CODE) \
 406         inline virtual MT& operator<<(__omanip_ func) CODE2 \
 407         inline virtual MT& operator<<(__manip_ func)  CODE2
 408
 409   #define GET_FUNC_SET1(MT,CODE,CODE2) \
 410           GET_PROT(MT,signed char &,CODE) \
 411           GET_PROT(MT,signed char *,CODE) \
 412           GET_FUNC_SET0(MT,CODE,CODE2)
 413
 414   #define PUT_FUNC_SET1(MT,CODE,CODE2) \
 415           PUT_FUNC(MT,signed char) \
 416           PUT_FUNC(MT,const signed char *) \
 417           PUT_FUNC_SET0(MT,CODE,CODE2)
 418
 419 #define GET_MANIP_CODE  { if (ipfx ()) { (*func) (*this); } isfx (); return *this; }
 420 #define PUT_MANIP_CODE  { if (opfx ()) { (*func) (*this); } osfx (); return *this; }
 421
 422 #define GET_FUNC_SET(MT)        GET_FUNC_SET1(MT,GET_CODE,GET_MANIP_CODE)
 423 #define PUT_FUNC_SET(MT)        PUT_FUNC_SET1(MT,PUT_CODE,PUT_MANIP_CODE)
 424 #define GETPUT_FUNC_SET(MT)     GET_FUNC_SET(MT) PUT_FUNC_SET(MT)
 425
 426 #define GET_SIG_SET(MT)         GET_FUNC_SET1(MT,= 0;,= 0;)
 427 #define PUT_SIG_SET(MT)         PUT_FUNC_SET1(MT,= 0;,= 0;)
 428 #define GETPUT_SIG_SET(MT)      GET_SIG_SET(MT) PUT_SIG_SET(MT)
 429
 430 // Include the templates here.
 431 #  include "ace/IOStream_T.h"
 432 #endif /* !ACE_LACKS_ACE_IOSTREAM && ACE_USES_OLD_IOSTREAMS */
 433
 434 #include /**/ "ace/post.h"
 435 #endif /* ACE_IOSTREAM_H */