Home | History | Annotate | Download | only in base
      1 /*
      2  * libjingle
      3  * Copyright 2004--2010, Google Inc.
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions are met:
      7  *
      8  *  1. Redistributions of source code must retain the above copyright notice,
      9  *     this list of conditions and the following disclaimer.
     10  *  2. Redistributions in binary form must reproduce the above copyright notice,
     11  *     this list of conditions and the following disclaimer in the documentation
     12  *     and/or other materials provided with the distribution.
     13  *  3. The name of the author may not be used to endorse or promote products
     14  *     derived from this software without specific prior written permission.
     15  *
     16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
     17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
     19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
     22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
     23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     26  */
     27 
     28 #ifndef TALK_BASE_STREAM_H_
     29 #define TALK_BASE_STREAM_H_
     30 
     31 #include "talk/base/basictypes.h"
     32 #include "talk/base/buffer.h"
     33 #include "talk/base/criticalsection.h"
     34 #include "talk/base/logging.h"
     35 #include "talk/base/messagehandler.h"
     36 #include "talk/base/messagequeue.h"
     37 #include "talk/base/scoped_ptr.h"
     38 #include "talk/base/sigslot.h"
     39 
     40 namespace talk_base {
     41 
     42 ///////////////////////////////////////////////////////////////////////////////
     43 // StreamInterface is a generic asynchronous stream interface, supporting read,
     44 // write, and close operations, and asynchronous signalling of state changes.
     45 // The interface is designed with file, memory, and socket implementations in
     46 // mind.  Some implementations offer extended operations, such as seeking.
     47 ///////////////////////////////////////////////////////////////////////////////
     48 
     49 // The following enumerations are declared outside of the StreamInterface
     50 // class for brevity in use.
     51 
     52 // The SS_OPENING state indicates that the stream will signal open or closed
     53 // in the future.
     54 enum StreamState { SS_CLOSED, SS_OPENING, SS_OPEN };
     55 
     56 // Stream read/write methods return this value to indicate various success
     57 // and failure conditions described below.
     58 enum StreamResult { SR_ERROR, SR_SUCCESS, SR_BLOCK, SR_EOS };
     59 
     60 // StreamEvents are used to asynchronously signal state transitionss.  The flags
     61 // may be combined.
     62 //  SE_OPEN: The stream has transitioned to the SS_OPEN state
     63 //  SE_CLOSE: The stream has transitioned to the SS_CLOSED state
     64 //  SE_READ: Data is available, so Read is likely to not return SR_BLOCK
     65 //  SE_WRITE: Data can be written, so Write is likely to not return SR_BLOCK
     66 enum StreamEvent { SE_OPEN = 1, SE_READ = 2, SE_WRITE = 4, SE_CLOSE = 8 };
     67 
     68 class Thread;
     69 
     70 struct StreamEventData : public MessageData {
     71   int events, error;
     72   StreamEventData(int ev, int er) : events(ev), error(er) { }
     73 };
     74 
     75 class StreamInterface : public MessageHandler {
     76  public:
     77   enum {
     78     MSG_POST_EVENT = 0xF1F1, MSG_MAX = MSG_POST_EVENT
     79   };
     80 
     81   virtual ~StreamInterface();
     82 
     83   virtual StreamState GetState() const = 0;
     84 
     85   // Read attempts to fill buffer of size buffer_len.  Write attempts to send
     86   // data_len bytes stored in data.  The variables read and write are set only
     87   // on SR_SUCCESS (see below).  Likewise, error is only set on SR_ERROR.
     88   // Read and Write return a value indicating:
     89   //  SR_ERROR: an error occurred, which is returned in a non-null error
     90   //    argument.  Interpretation of the error requires knowledge of the
     91   //    stream's concrete type, which limits its usefulness.
     92   //  SR_SUCCESS: some number of bytes were successfully written, which is
     93   //    returned in a non-null read/write argument.
     94   //  SR_BLOCK: the stream is in non-blocking mode, and the operation would
     95   //    block, or the stream is in SS_OPENING state.
     96   //  SR_EOS: the end-of-stream has been reached, or the stream is in the
     97   //    SS_CLOSED state.
     98   virtual StreamResult Read(void* buffer, size_t buffer_len,
     99                             size_t* read, int* error) = 0;
    100   virtual StreamResult Write(const void* data, size_t data_len,
    101                              size_t* written, int* error) = 0;
    102   // Attempt to transition to the SS_CLOSED state.  SE_CLOSE will not be
    103   // signalled as a result of this call.
    104   virtual void Close() = 0;
    105 
    106   // Streams may signal one or more StreamEvents to indicate state changes.
    107   // The first argument identifies the stream on which the state change occured.
    108   // The second argument is a bit-wise combination of StreamEvents.
    109   // If SE_CLOSE is signalled, then the third argument is the associated error
    110   // code.  Otherwise, the value is undefined.
    111   // Note: Not all streams will support asynchronous event signalling.  However,
    112   // SS_OPENING and SR_BLOCK returned from stream member functions imply that
    113   // certain events will be raised in the future.
    114   sigslot::signal3<StreamInterface*, int, int> SignalEvent;
    115 
    116   // Like calling SignalEvent, but posts a message to the specified thread,
    117   // which will call SignalEvent.  This helps unroll the stack and prevent
    118   // re-entrancy.
    119   void PostEvent(Thread* t, int events, int err);
    120   // Like the aforementioned method, but posts to the current thread.
    121   void PostEvent(int events, int err);
    122 
    123   //
    124   // OPTIONAL OPERATIONS
    125   //
    126   // Not all implementations will support the following operations.  In general,
    127   // a stream will only support an operation if it reasonably efficient to do
    128   // so.  For example, while a socket could buffer incoming data to support
    129   // seeking, it will not do so.  Instead, a buffering stream adapter should
    130   // be used.
    131   //
    132   // Even though several of these operations are related, you should
    133   // always use whichever operation is most relevant.  For example, you may
    134   // be tempted to use GetSize() and GetPosition() to deduce the result of
    135   // GetAvailable().  However, a stream which is read-once may support the
    136   // latter operation but not the former.
    137   //
    138 
    139   // The following four methods are used to avoid copying data multiple times.
    140 
    141   // GetReadData returns a pointer to a buffer which is owned by the stream.
    142   // The buffer contains data_len bytes.  NULL is returned if no data is
    143   // available, or if the method fails.  If the caller processes the data, it
    144   // must call ConsumeReadData with the number of processed bytes.  GetReadData
    145   // does not require a matching call to ConsumeReadData if the data is not
    146   // processed.  Read and ConsumeReadData invalidate the buffer returned by
    147   // GetReadData.
    148   virtual const void* GetReadData(size_t* data_len) { return NULL; }
    149   virtual void ConsumeReadData(size_t used) {}
    150 
    151   // GetWriteBuffer returns a pointer to a buffer which is owned by the stream.
    152   // The buffer has a capacity of buf_len bytes.  NULL is returned if there is
    153   // no buffer available, or if the method fails.  The call may write data to
    154   // the buffer, and then call ConsumeWriteBuffer with the number of bytes
    155   // written.  GetWriteBuffer does not require a matching call to
    156   // ConsumeWriteData if no data is written.  Write, ForceWrite, and
    157   // ConsumeWriteData invalidate the buffer returned by GetWriteBuffer.
    158   // TODO: Allow the caller to specify a minimum buffer size.  If the specified
    159   // amount of buffer is not yet available, return NULL and Signal SE_WRITE
    160   // when it is available.  If the requested amount is too large, return an
    161   // error.
    162   virtual void* GetWriteBuffer(size_t* buf_len) { return NULL; }
    163   virtual void ConsumeWriteBuffer(size_t used) {}
    164 
    165   // Write data_len bytes found in data, circumventing any throttling which
    166   // would could cause SR_BLOCK to be returned.  Returns true if all the data
    167   // was written.  Otherwise, the method is unsupported, or an unrecoverable
    168   // error occurred, and the error value is set.  This method should be used
    169   // sparingly to write critical data which should not be throttled.  A stream
    170   // which cannot circumvent its blocking constraints should not implement this
    171   // method.
    172   // NOTE: This interface is being considered experimentally at the moment.  It
    173   // would be used by JUDP and BandwidthStream as a way to circumvent certain
    174   // soft limits in writing.
    175   //virtual bool ForceWrite(const void* data, size_t data_len, int* error) {
    176   //  if (error) *error = -1;
    177   //  return false;
    178   //}
    179 
    180   // Seek to a byte offset from the beginning of the stream.  Returns false if
    181   // the stream does not support seeking, or cannot seek to the specified
    182   // position.
    183   virtual bool SetPosition(size_t position) { return false; }
    184 
    185   // Get the byte offset of the current position from the start of the stream.
    186   // Returns false if the position is not known.
    187   virtual bool GetPosition(size_t* position) const { return false; }
    188 
    189   // Get the byte length of the entire stream.  Returns false if the length
    190   // is not known.
    191   virtual bool GetSize(size_t* size) const { return false; }
    192 
    193   // Return the number of Read()-able bytes remaining before end-of-stream.
    194   // Returns false if not known.
    195   virtual bool GetAvailable(size_t* size) const { return false; }
    196 
    197   // Return the number of Write()-able bytes remaining before end-of-stream.
    198   // Returns false if not known.
    199   virtual bool GetWriteRemaining(size_t* size) const { return false; }
    200 
    201   // Return true if flush is successful.
    202   virtual bool Flush() { return false; }
    203 
    204   // Communicates the amount of data which will be written to the stream.  The
    205   // stream may choose to preallocate memory to accomodate this data.  The
    206   // stream may return false to indicate that there is not enough room (ie,
    207   // Write will return SR_EOS/SR_ERROR at some point).  Note that calling this
    208   // function should not affect the existing state of data in the stream.
    209   virtual bool ReserveSize(size_t size) { return true; }
    210 
    211   //
    212   // CONVENIENCE METHODS
    213   //
    214   // These methods are implemented in terms of other methods, for convenience.
    215   //
    216 
    217   // Seek to the start of the stream.
    218   inline bool Rewind() { return SetPosition(0); }
    219 
    220   // WriteAll is a helper function which repeatedly calls Write until all the
    221   // data is written, or something other than SR_SUCCESS is returned.  Note that
    222   // unlike Write, the argument 'written' is always set, and may be non-zero
    223   // on results other than SR_SUCCESS.  The remaining arguments have the
    224   // same semantics as Write.
    225   StreamResult WriteAll(const void* data, size_t data_len,
    226                         size_t* written, int* error);
    227 
    228   // Similar to ReadAll.  Calls Read until buffer_len bytes have been read, or
    229   // until a non-SR_SUCCESS result is returned.  'read' is always set.
    230   StreamResult ReadAll(void* buffer, size_t buffer_len,
    231                        size_t* read, int* error);
    232 
    233   // ReadLine is a helper function which repeatedly calls Read until it hits
    234   // the end-of-line character, or something other than SR_SUCCESS.
    235   // TODO: this is too inefficient to keep here.  Break this out into a buffered
    236   // readline object or adapter
    237   StreamResult ReadLine(std::string* line);
    238 
    239  protected:
    240   StreamInterface();
    241 
    242   // MessageHandler Interface
    243   virtual void OnMessage(Message* msg);
    244 
    245  private:
    246   DISALLOW_EVIL_CONSTRUCTORS(StreamInterface);
    247 };
    248 
    249 ///////////////////////////////////////////////////////////////////////////////
    250 // StreamAdapterInterface is a convenient base-class for adapting a stream.
    251 // By default, all operations are pass-through.  Override the methods that you
    252 // require adaptation.  Streams should really be upgraded to reference-counted.
    253 // In the meantime, use the owned flag to indicate whether the adapter should
    254 // own the adapted stream.
    255 ///////////////////////////////////////////////////////////////////////////////
    256 
    257 class StreamAdapterInterface : public StreamInterface,
    258                                public sigslot::has_slots<> {
    259  public:
    260   explicit StreamAdapterInterface(StreamInterface* stream, bool owned = true);
    261 
    262   // Core Stream Interface
    263   virtual StreamState GetState() const {
    264     return stream_->GetState();
    265   }
    266   virtual StreamResult Read(void* buffer, size_t buffer_len,
    267                             size_t* read, int* error) {
    268     return stream_->Read(buffer, buffer_len, read, error);
    269   }
    270   virtual StreamResult Write(const void* data, size_t data_len,
    271                              size_t* written, int* error) {
    272     return stream_->Write(data, data_len, written, error);
    273   }
    274   virtual void Close() {
    275     stream_->Close();
    276   }
    277 
    278   // Optional Stream Interface
    279   /*  Note: Many stream adapters were implemented prior to this Read/Write
    280       interface.  Therefore, a simple pass through of data in those cases may
    281       be broken.  At a later time, we should do a once-over pass of all
    282       adapters, and make them compliant with these interfaces, after which this
    283       code can be uncommented.
    284   virtual const void* GetReadData(size_t* data_len) {
    285     return stream_->GetReadData(data_len);
    286   }
    287   virtual void ConsumeReadData(size_t used) {
    288     stream_->ConsumeReadData(used);
    289   }
    290 
    291   virtual void* GetWriteBuffer(size_t* buf_len) {
    292     return stream_->GetWriteBuffer(buf_len);
    293   }
    294   virtual void ConsumeWriteBuffer(size_t used) {
    295     stream_->ConsumeWriteBuffer(used);
    296   }
    297   */
    298 
    299   /*  Note: This interface is currently undergoing evaluation.
    300   virtual bool ForceWrite(const void* data, size_t data_len, int* error) {
    301     return stream_->ForceWrite(data, data_len, error);
    302   }
    303   */
    304 
    305   virtual bool SetPosition(size_t position) {
    306     return stream_->SetPosition(position);
    307   }
    308   virtual bool GetPosition(size_t* position) const {
    309     return stream_->GetPosition(position);
    310   }
    311   virtual bool GetSize(size_t* size) const {
    312     return stream_->GetSize(size);
    313   }
    314   virtual bool GetAvailable(size_t* size) const {
    315     return stream_->GetAvailable(size);
    316   }
    317   virtual bool GetWriteRemaining(size_t* size) const {
    318     return stream_->GetWriteRemaining(size);
    319   }
    320   virtual bool ReserveSize(size_t size) {
    321     return stream_->ReserveSize(size);
    322   }
    323   virtual bool Flush() {
    324     return stream_->Flush();
    325   }
    326 
    327   void Attach(StreamInterface* stream, bool owned = true);
    328   StreamInterface* Detach();
    329 
    330  protected:
    331   virtual ~StreamAdapterInterface();
    332 
    333   // Note that the adapter presents itself as the origin of the stream events,
    334   // since users of the adapter may not recognize the adapted object.
    335   virtual void OnEvent(StreamInterface* stream, int events, int err) {
    336     SignalEvent(this, events, err);
    337   }
    338   StreamInterface* stream() { return stream_; }
    339 
    340  private:
    341   StreamInterface* stream_;
    342   bool owned_;
    343   DISALLOW_EVIL_CONSTRUCTORS(StreamAdapterInterface);
    344 };
    345 
    346 ///////////////////////////////////////////////////////////////////////////////
    347 // StreamTap is a non-modifying, pass-through adapter, which copies all data
    348 // in either direction to the tap.  Note that errors or blocking on writing to
    349 // the tap will prevent further tap writes from occurring.
    350 ///////////////////////////////////////////////////////////////////////////////
    351 
    352 class StreamTap : public StreamAdapterInterface {
    353  public:
    354   explicit StreamTap(StreamInterface* stream, StreamInterface* tap);
    355 
    356   void AttachTap(StreamInterface* tap);
    357   StreamInterface* DetachTap();
    358   StreamResult GetTapResult(int* error);
    359 
    360   // StreamAdapterInterface Interface
    361   virtual StreamResult Read(void* buffer, size_t buffer_len,
    362                             size_t* read, int* error);
    363   virtual StreamResult Write(const void* data, size_t data_len,
    364                              size_t* written, int* error);
    365 
    366  private:
    367   scoped_ptr<StreamInterface> tap_;
    368   StreamResult tap_result_;
    369   int tap_error_;
    370   DISALLOW_EVIL_CONSTRUCTORS(StreamTap);
    371 };
    372 
    373 ///////////////////////////////////////////////////////////////////////////////
    374 // StreamSegment adapts a read stream, to expose a subset of the adapted
    375 // stream's data.  This is useful for cases where a stream contains multiple
    376 // documents concatenated together.  StreamSegment can expose a subset of
    377 // the data as an independent stream, including support for rewinding and
    378 // seeking.
    379 ///////////////////////////////////////////////////////////////////////////////
    380 
    381 class StreamSegment : public StreamAdapterInterface {
    382  public:
    383   // The current position of the adapted stream becomes the beginning of the
    384   // segment.  If a length is specified, it bounds the length of the segment.
    385   explicit StreamSegment(StreamInterface* stream);
    386   explicit StreamSegment(StreamInterface* stream, size_t length);
    387 
    388   // StreamAdapterInterface Interface
    389   virtual StreamResult Read(void* buffer, size_t buffer_len,
    390                             size_t* read, int* error);
    391   virtual bool SetPosition(size_t position);
    392   virtual bool GetPosition(size_t* position) const;
    393   virtual bool GetSize(size_t* size) const;
    394   virtual bool GetAvailable(size_t* size) const;
    395 
    396  private:
    397   size_t start_, pos_, length_;
    398   DISALLOW_EVIL_CONSTRUCTORS(StreamSegment);
    399 };
    400 
    401 ///////////////////////////////////////////////////////////////////////////////
    402 // NullStream gives errors on read, and silently discards all written data.
    403 ///////////////////////////////////////////////////////////////////////////////
    404 
    405 class NullStream : public StreamInterface {
    406  public:
    407   NullStream();
    408   virtual ~NullStream();
    409 
    410   // StreamInterface Interface
    411   virtual StreamState GetState() const;
    412   virtual StreamResult Read(void* buffer, size_t buffer_len,
    413                             size_t* read, int* error);
    414   virtual StreamResult Write(const void* data, size_t data_len,
    415                              size_t* written, int* error);
    416   virtual void Close();
    417 };
    418 
    419 ///////////////////////////////////////////////////////////////////////////////
    420 // FileStream is a simple implementation of a StreamInterface, which does not
    421 // support asynchronous notification.
    422 ///////////////////////////////////////////////////////////////////////////////
    423 
    424 class FileStream : public StreamInterface {
    425  public:
    426   FileStream();
    427   virtual ~FileStream();
    428 
    429   // The semantics of filename and mode are the same as stdio's fopen
    430   virtual bool Open(const std::string& filename, const char* mode, int* error);
    431   virtual bool OpenShare(const std::string& filename, const char* mode,
    432                          int shflag, int* error);
    433 
    434   // By default, reads and writes are buffered for efficiency.  Disabling
    435   // buffering causes writes to block until the bytes on disk are updated.
    436   virtual bool DisableBuffering();
    437 
    438   virtual StreamState GetState() const;
    439   virtual StreamResult Read(void* buffer, size_t buffer_len,
    440                             size_t* read, int* error);
    441   virtual StreamResult Write(const void* data, size_t data_len,
    442                              size_t* written, int* error);
    443   virtual void Close();
    444   virtual bool SetPosition(size_t position);
    445   virtual bool GetPosition(size_t* position) const;
    446   virtual bool GetSize(size_t* size) const;
    447   virtual bool GetAvailable(size_t* size) const;
    448   virtual bool ReserveSize(size_t size);
    449 
    450   virtual bool Flush();
    451 
    452 #if defined(POSIX)
    453   // Tries to aquire an exclusive lock on the file.
    454   // Use OpenShare(...) on win32 to get similar functionality.
    455   bool TryLock();
    456   bool Unlock();
    457 #endif
    458 
    459   // Note: Deprecated in favor of Filesystem::GetFileSize().
    460   static bool GetSize(const std::string& filename, size_t* size);
    461 
    462  protected:
    463   virtual void DoClose();
    464 
    465   FILE* file_;
    466 
    467  private:
    468   DISALLOW_EVIL_CONSTRUCTORS(FileStream);
    469 };
    470 
    471 // A stream that caps the output at a certain size, dropping content from the
    472 // middle of the logical stream and maintaining equal parts of the start/end of
    473 // the logical stream.
    474 class CircularFileStream : public FileStream {
    475  public:
    476   explicit CircularFileStream(size_t max_size);
    477 
    478   virtual bool Open(const std::string& filename, const char* mode, int* error);
    479   virtual StreamResult Read(void* buffer, size_t buffer_len,
    480                             size_t* read, int* error);
    481   virtual StreamResult Write(const void* data, size_t data_len,
    482                              size_t* written, int* error);
    483 
    484  private:
    485   enum ReadSegment {
    486     READ_MARKED,  // Read 0 .. marked_position_
    487     READ_MIDDLE,  // Read position_ .. file_size
    488     READ_LATEST,  // Read marked_position_ .. position_ if the buffer was
    489                   // overwritten or 0 .. position_ otherwise.
    490   };
    491 
    492   size_t max_write_size_;
    493   size_t position_;
    494   size_t marked_position_;
    495   size_t last_write_position_;
    496   ReadSegment read_segment_;
    497   size_t read_segment_available_;
    498 };
    499 
    500 
    501 // A stream which pushes writes onto a separate thread and
    502 // returns from the write call immediately.
    503 class AsyncWriteStream : public StreamInterface {
    504  public:
    505   // Takes ownership of the stream, but not the thread.
    506   AsyncWriteStream(StreamInterface* stream, talk_base::Thread* write_thread)
    507       : stream_(stream),
    508         write_thread_(write_thread),
    509         state_(stream ? stream->GetState() : SS_CLOSED) {
    510   }
    511 
    512   virtual ~AsyncWriteStream();
    513 
    514   // StreamInterface Interface
    515   virtual StreamState GetState() const { return state_; }
    516   // This is needed by some stream writers, such as RtpDumpWriter.
    517   virtual bool GetPosition(size_t* position) const;
    518   virtual StreamResult Read(void* buffer, size_t buffer_len,
    519                             size_t* read, int* error);
    520   virtual StreamResult Write(const void* data, size_t data_len,
    521                              size_t* written, int* error);
    522   virtual void Close();
    523   virtual bool Flush();
    524 
    525  protected:
    526   // From MessageHandler
    527   virtual void OnMessage(talk_base::Message* pmsg);
    528   virtual void ClearBufferAndWrite();
    529 
    530  private:
    531   talk_base::scoped_ptr<StreamInterface> stream_;
    532   Thread* write_thread_;
    533   StreamState state_;
    534   Buffer buffer_;
    535   mutable CriticalSection crit_stream_;
    536   CriticalSection crit_buffer_;
    537 
    538   DISALLOW_EVIL_CONSTRUCTORS(AsyncWriteStream);
    539 };
    540 
    541 
    542 #ifdef POSIX
    543 // A FileStream that is actually not a file, but the output or input of a
    544 // sub-command. See "man 3 popen" for documentation of the underlying OS popen()
    545 // function.
    546 class POpenStream : public FileStream {
    547  public:
    548   POpenStream() : wait_status_(-1) {}
    549   virtual ~POpenStream();
    550 
    551   virtual bool Open(const std::string& subcommand, const char* mode,
    552                     int* error);
    553   // Same as Open(). shflag is ignored.
    554   virtual bool OpenShare(const std::string& subcommand, const char* mode,
    555                          int shflag, int* error);
    556 
    557   // Returns the wait status from the last Close() of an Open()'ed stream, or
    558   // -1 if no Open()+Close() has been done on this object. Meaning of the number
    559   // is documented in "man 2 wait".
    560   int GetWaitStatus() const { return wait_status_; }
    561 
    562  protected:
    563   virtual void DoClose();
    564 
    565  private:
    566   int wait_status_;
    567 };
    568 #endif  // POSIX
    569 
    570 ///////////////////////////////////////////////////////////////////////////////
    571 // MemoryStream is a simple implementation of a StreamInterface over in-memory
    572 // data.  Data is read and written at the current seek position.  Reads return
    573 // end-of-stream when they reach the end of data.  Writes actually extend the
    574 // end of data mark.
    575 ///////////////////////////////////////////////////////////////////////////////
    576 
    577 class MemoryStreamBase : public StreamInterface {
    578  public:
    579   virtual StreamState GetState() const;
    580   virtual StreamResult Read(void* buffer, size_t bytes, size_t* bytes_read,
    581                             int* error);
    582   virtual StreamResult Write(const void* buffer, size_t bytes,
    583                              size_t* bytes_written, int* error);
    584   virtual void Close();
    585   virtual bool SetPosition(size_t position);
    586   virtual bool GetPosition(size_t* position) const;
    587   virtual bool GetSize(size_t* size) const;
    588   virtual bool GetAvailable(size_t* size) const;
    589   virtual bool ReserveSize(size_t size);
    590 
    591   char* GetBuffer() { return buffer_; }
    592   const char* GetBuffer() const { return buffer_; }
    593 
    594  protected:
    595   MemoryStreamBase();
    596 
    597   virtual StreamResult DoReserve(size_t size, int* error);
    598 
    599   // Invariant: 0 <= seek_position <= data_length_ <= buffer_length_
    600   char* buffer_;
    601   size_t buffer_length_;
    602   size_t data_length_;
    603   size_t seek_position_;
    604 
    605  private:
    606   DISALLOW_EVIL_CONSTRUCTORS(MemoryStreamBase);
    607 };
    608 
    609 // MemoryStream dynamically resizes to accomodate written data.
    610 
    611 class MemoryStream : public MemoryStreamBase {
    612  public:
    613   MemoryStream();
    614   explicit MemoryStream(const char* data);  // Calls SetData(data, strlen(data))
    615   MemoryStream(const void* data, size_t length);  // Calls SetData(data, length)
    616   virtual ~MemoryStream();
    617 
    618   void SetData(const void* data, size_t length);
    619 
    620  protected:
    621   virtual StreamResult DoReserve(size_t size, int* error);
    622   // Memory Streams are aligned for efficiency.
    623   static const int kAlignment = 16;
    624   char* buffer_alloc_;
    625 };
    626 
    627 // ExternalMemoryStream adapts an external memory buffer, so writes which would
    628 // extend past the end of the buffer will return end-of-stream.
    629 
    630 class ExternalMemoryStream : public MemoryStreamBase {
    631  public:
    632   ExternalMemoryStream();
    633   ExternalMemoryStream(void* data, size_t length);
    634   virtual ~ExternalMemoryStream();
    635 
    636   void SetData(void* data, size_t length);
    637 };
    638 
    639 // FifoBuffer allows for efficient, thread-safe buffering of data between
    640 // writer and reader. As the data can wrap around the end of the buffer,
    641 // MemoryStreamBase can't help us here.
    642 
    643 class FifoBuffer : public StreamInterface {
    644  public:
    645   // Creates a FIFO buffer with the specified capacity.
    646   explicit FifoBuffer(size_t length);
    647   // Creates a FIFO buffer with the specified capacity and owner
    648   FifoBuffer(size_t length, Thread* owner);
    649   virtual ~FifoBuffer();
    650   // Gets the amount of data currently readable from the buffer.
    651   bool GetBuffered(size_t* data_len) const;
    652   // Resizes the buffer to the specified capacity. Fails if data_length_ > size
    653   bool SetCapacity(size_t length);
    654 
    655   // Read into |buffer| with an offset from the current read position, offset
    656   // is specified in number of bytes.
    657   // This method doesn't adjust read position nor the number of available
    658   // bytes, user has to call ConsumeReadData() to do this.
    659   StreamResult ReadOffset(void* buffer, size_t bytes, size_t offset,
    660                           size_t* bytes_read);
    661 
    662   // Write |buffer| with an offset from the current write position, offset is
    663   // specified in number of bytes.
    664   // This method doesn't adjust the number of buffered bytes, user has to call
    665   // ConsumeWriteBuffer() to do this.
    666   StreamResult WriteOffset(const void* buffer, size_t bytes, size_t offset,
    667                            size_t* bytes_written);
    668 
    669   // StreamInterface methods
    670   virtual StreamState GetState() const;
    671   virtual StreamResult Read(void* buffer, size_t bytes,
    672                             size_t* bytes_read, int* error);
    673   virtual StreamResult Write(const void* buffer, size_t bytes,
    674                              size_t* bytes_written, int* error);
    675   virtual void Close();
    676   virtual const void* GetReadData(size_t* data_len);
    677   virtual void ConsumeReadData(size_t used);
    678   virtual void* GetWriteBuffer(size_t* buf_len);
    679   virtual void ConsumeWriteBuffer(size_t used);
    680   virtual bool GetWriteRemaining(size_t* size) const;
    681 
    682  private:
    683   // Helper method that implements ReadOffset. Caller must acquire a lock
    684   // when calling this method.
    685   StreamResult ReadOffsetLocked(void* buffer, size_t bytes, size_t offset,
    686                                 size_t* bytes_read);
    687 
    688   // Helper method that implements WriteOffset. Caller must acquire a lock
    689   // when calling this method.
    690   StreamResult WriteOffsetLocked(const void* buffer, size_t bytes,
    691                                  size_t offset, size_t* bytes_written);
    692 
    693   StreamState state_;  // keeps the opened/closed state of the stream
    694   scoped_ptr<char[]> buffer_;  // the allocated buffer
    695   size_t buffer_length_;  // size of the allocated buffer
    696   size_t data_length_;  // amount of readable data in the buffer
    697   size_t read_position_;  // offset to the readable data
    698   Thread* owner_;  // stream callbacks are dispatched on this thread
    699   mutable CriticalSection crit_;  // object lock
    700   DISALLOW_EVIL_CONSTRUCTORS(FifoBuffer);
    701 };
    702 
    703 ///////////////////////////////////////////////////////////////////////////////
    704 
    705 class LoggingAdapter : public StreamAdapterInterface {
    706  public:
    707   LoggingAdapter(StreamInterface* stream, LoggingSeverity level,
    708                  const std::string& label, bool hex_mode = false);
    709 
    710   void set_label(const std::string& label);
    711 
    712   virtual StreamResult Read(void* buffer, size_t buffer_len,
    713                             size_t* read, int* error);
    714   virtual StreamResult Write(const void* data, size_t data_len,
    715                              size_t* written, int* error);
    716   virtual void Close();
    717 
    718  protected:
    719   virtual void OnEvent(StreamInterface* stream, int events, int err);
    720 
    721  private:
    722   LoggingSeverity level_;
    723   std::string label_;
    724   bool hex_mode_;
    725   LogMultilineState lms_;
    726 
    727   DISALLOW_EVIL_CONSTRUCTORS(LoggingAdapter);
    728 };
    729 
    730 ///////////////////////////////////////////////////////////////////////////////
    731 // StringStream - Reads/Writes to an external std::string
    732 ///////////////////////////////////////////////////////////////////////////////
    733 
    734 class StringStream : public StreamInterface {
    735  public:
    736   explicit StringStream(std::string& str);
    737   explicit StringStream(const std::string& str);
    738 
    739   virtual StreamState GetState() const;
    740   virtual StreamResult Read(void* buffer, size_t buffer_len,
    741                             size_t* read, int* error);
    742   virtual StreamResult Write(const void* data, size_t data_len,
    743                              size_t* written, int* error);
    744   virtual void Close();
    745   virtual bool SetPosition(size_t position);
    746   virtual bool GetPosition(size_t* position) const;
    747   virtual bool GetSize(size_t* size) const;
    748   virtual bool GetAvailable(size_t* size) const;
    749   virtual bool ReserveSize(size_t size);
    750 
    751  private:
    752   std::string& str_;
    753   size_t read_pos_;
    754   bool read_only_;
    755 };
    756 
    757 ///////////////////////////////////////////////////////////////////////////////
    758 // StreamReference - A reference counting stream adapter
    759 ///////////////////////////////////////////////////////////////////////////////
    760 
    761 // Keep in mind that the streams and adapters defined in this file are
    762 // not thread-safe, so this has limited uses.
    763 
    764 // A StreamRefCount holds the reference count and a pointer to the
    765 // wrapped stream. It deletes the wrapped stream when there are no
    766 // more references. We can then have multiple StreamReference
    767 // instances pointing to one StreamRefCount, all wrapping the same
    768 // stream.
    769 
    770 class StreamReference : public StreamAdapterInterface {
    771   class StreamRefCount;
    772  public:
    773   // Constructor for the first reference to a stream
    774   // Note: get more references through NewReference(). Use this
    775   // constructor only once on a given stream.
    776   explicit StreamReference(StreamInterface* stream);
    777   StreamInterface* GetStream() { return stream(); }
    778   StreamInterface* NewReference();
    779   virtual ~StreamReference();
    780 
    781  private:
    782   class StreamRefCount {
    783    public:
    784     explicit StreamRefCount(StreamInterface* stream)
    785         : stream_(stream), ref_count_(1) {
    786     }
    787     void AddReference() {
    788       CritScope lock(&cs_);
    789       ++ref_count_;
    790     }
    791     void Release() {
    792       int ref_count;
    793       {  // Atomic ops would have been a better fit here.
    794         CritScope lock(&cs_);
    795         ref_count = --ref_count_;
    796       }
    797       if (ref_count == 0) {
    798         delete stream_;
    799         delete this;
    800       }
    801     }
    802    private:
    803     StreamInterface* stream_;
    804     int ref_count_;
    805     CriticalSection cs_;
    806     DISALLOW_EVIL_CONSTRUCTORS(StreamRefCount);
    807   };
    808 
    809   // Constructor for adding references
    810   explicit StreamReference(StreamRefCount* stream_ref_count,
    811                            StreamInterface* stream);
    812 
    813   StreamRefCount* stream_ref_count_;
    814   DISALLOW_EVIL_CONSTRUCTORS(StreamReference);
    815 };
    816 
    817 ///////////////////////////////////////////////////////////////////////////////
    818 
    819 // Flow attempts to move bytes from source to sink via buffer of size
    820 // buffer_len.  The function returns SR_SUCCESS when source reaches
    821 // end-of-stream (returns SR_EOS), and all the data has been written successful
    822 // to sink.  Alternately, if source returns SR_BLOCK or SR_ERROR, or if sink
    823 // returns SR_BLOCK, SR_ERROR, or SR_EOS, then the function immediately returns
    824 // with the unexpected StreamResult value.
    825 // data_len is the length of the valid data in buffer. in case of error
    826 // this is the data that read from source but can't move to destination.
    827 // as a pass in parameter, it indicates data in buffer that should move to sink
    828 StreamResult Flow(StreamInterface* source,
    829                   char* buffer, size_t buffer_len,
    830                   StreamInterface* sink, size_t* data_len = NULL);
    831 
    832 ///////////////////////////////////////////////////////////////////////////////
    833 
    834 }  // namespace talk_base
    835 
    836 #endif  // TALK_BASE_STREAM_H_
    837