courgette/streams.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Streams classes.
   6 //
   7 // These memory-resident streams are used for serializing data into a sequential
   8 // region of memory.
   9 // Streams are divided into SourceStreams for reading and SinkStreams for
  10 // writing.  Streams are aggregated into Sets which allows several streams to be
  11 // used at once.  Example: we can write A1, B1, A2, B2 but achieve the memory
  12 // layout A1 A2 B1 B2 by writing 'A's to one stream and 'B's to another.
  13
  14 #ifndef COURGETTE_STREAMS_H_
  15 #define COURGETTE_STREAMS_H_
  16
  17 #include <stddef.h>
  18 #include <stdint.h>
  19 #include <stdio.h>  // for FILE*
  20 #include <string>
  21
  22 #include "base/compiler_specific.h"
  23 #include "base/macros.h"
  24 #include "courgette/memory_allocator.h"
  25 #include "courgette/region.h"
  26
  27
  28 namespace courgette {
  29
  30 class SourceStream;
  31 class SinkStream;
  32
  33 // Maximum number of streams in a stream set.
  34 static const unsigned int kMaxStreams = 10;
  35
  36 // A simple interface for reading binary data.
  37 class BasicBuffer {
  38  public:
  39   BasicBuffer() {}
  40   virtual ~BasicBuffer() {}
  41   virtual const uint8_t* data() const = 0;
  42   virtual size_t length() const = 0;
  43 };
  44
  45 // A SourceStream allows a region of memory to be scanned by a sequence of Read
  46 // operations.  The stream does not own the memory.
  47 class SourceStream {
  48  public:
  49   SourceStream() : start_(NULL), end_(NULL), current_(NULL) {}
  50
  51   // Initializes the SourceStream to yield the bytes at |pointer|.  The caller
  52   // still owns the memory at |pointer| and should free the memory only after
  53   // the last use of the stream.
  54   void Init(const void* pointer, size_t length) {
  55     start_ = static_cast<const uint8_t*>(pointer);
  56     end_ = start_ + length;
  57     current_ = start_;
  58   }
  59
  60   // Initializes the SourceStream to yield the bytes in |region|.  The caller
  61   // still owns the memory at |region| and should free the memory only after
  62   // the last use of the stream.
  63   void Init(const Region& region) { Init(region.start(), region.length()); }
  64
  65   // Initializes the SourceStream to yield the bytes in |string|.  The caller
  66   // still owns the memory at |string| and should free the memory only after
  67   // the last use of the stream.
  68   void Init(const std::string& string) { Init(string.c_str(), string.size()); }
  69
  70   // Initializes the SourceStream to yield the bytes written to |sink|. |sink|
  71   // still owns the memory, so needs to outlive |this|.  |sink| should not be
  72   // written to after |this| is initialized.
  73   void Init(const SinkStream& sink);
  74
  75   // Returns number of bytes remaining to be read from stream.
  76   size_t Remaining() const { return end_ - current_; }
  77
  78   // Returns initial length of stream before any data consumed by reading.
  79   size_t OriginalLength() const { return end_ - start_; }
  80
  81   const uint8_t* Buffer() const { return current_; }
  82   bool Empty() const { return current_ == end_; }
  83
  84   // Copies bytes from stream to memory at |destination|.  Returns 'false' if
  85   // insufficient data to satisfy request.
  86   bool Read(void* destination, size_t byte_count);
  87
  88   // Reads a varint formatted unsigned integer from stream.  Returns 'false' if
  89   // the read failed due to insufficient data or malformed Varint32.
  90   bool ReadVarint32(uint32_t* output_value);
  91
  92   // Reads a varint formatted signed integer from stream.  Returns 'false' if
  93   // the read failed due to insufficient data or malformed Varint32.
  94   bool ReadVarint32Signed(int32_t* output_value);
  95
  96   // Initializes |substream| to yield |length| bytes from |this| stream,
  97   // starting at |offset| bytes from the current position.  Returns 'false' if
  98   // there are insufficient bytes in |this| stream.
  99   bool ShareSubstream(size_t offset, size_t length, SourceStream* substream);
 100
 101   // Initializes |substream| to yield |length| bytes from |this| stream,
 102   // starting at the current position.  Returns 'false' if there are
 103   // insufficient bytes in |this| stream.
 104   bool ShareSubstream(size_t length, SourceStream* substream) {
 105     return ShareSubstream(0, length, substream);
 106   }
 107
 108   // Reads |length| bytes from |this| stream.  Initializes |substream| to yield
 109   // the bytes.  Returns 'false' if there are insufficient bytes in |this|
 110   // stream.
 111   bool ReadSubstream(size_t length, SourceStream* substream);
 112
 113   // Skips over bytes.  Returns 'false' if insufficient data to satisfy request.
 114   bool Skip(size_t byte_count);
 115
 116  private:
 117   const uint8_t* start_;    // Points to start of buffer.
 118   const uint8_t* end_;      // Points to first location after buffer.
 119   const uint8_t* current_;  // Points into buffer at current read location.
 120
 121   DISALLOW_COPY_AND_ASSIGN(SourceStream);
 122 };
 123
 124 // A SinkStream accumulates writes into a buffer that it owns.  The stream is
 125 // initially in an 'accumulating' state where writes are permitted.  Accessing
 126 // the buffer moves the stream into a 'locked' state where no more writes are
 127 // permitted.  The stream may also be in a 'retired' state where the buffer
 128 // contents are no longer available.
 129 class SinkStream {
 130  public:
 131   SinkStream() {}
 132   ~SinkStream() {}
 133
 134   // Appends |byte_count| bytes from |data| to the stream.
 135   CheckBool Write(const void* data, size_t byte_count) WARN_UNUSED_RESULT;
 136
 137   // Appends the 'varint32' encoding of |value| to the stream.
 138   CheckBool WriteVarint32(uint32_t value) WARN_UNUSED_RESULT;
 139
 140   // Appends the 'varint32' encoding of |value| to the stream.
 141   CheckBool WriteVarint32Signed(int32_t value) WARN_UNUSED_RESULT;
 142
 143   // Appends the 'varint32' encoding of |value| to the stream.
 144   // On platforms where sizeof(size_t) != sizeof(int32_t), do a safety check.
 145   CheckBool WriteSizeVarint32(size_t value) WARN_UNUSED_RESULT;
 146
 147   // Contents of |other| are appended to |this| stream.  The |other| stream
 148   // becomes retired.
 149   CheckBool Append(SinkStream* other) WARN_UNUSED_RESULT;
 150
 151   // Returns the number of bytes in this SinkStream
 152   size_t Length() const { return buffer_.size(); }
 153
 154   // Returns a pointer to contiguously allocated Length() bytes in the stream.
 155   // Writing to the stream invalidates the pointer.  The SinkStream continues to
 156   // own the memory.
 157   const uint8_t* Buffer() const {
 158     return reinterpret_cast<const uint8_t*>(buffer_.data());
 159   }
 160
 161   // Hints that the stream will grow by an additional |length| bytes.
 162   // Caller must be prepared to handle memory allocation problems.
 163   CheckBool Reserve(size_t length) WARN_UNUSED_RESULT {
 164     return buffer_.reserve(length + buffer_.size());
 165   }
 166
 167   // Finished with this stream and any storage it has.
 168   void Retire();
 169
 170  private:
 171   NoThrowBuffer<char> buffer_;
 172
 173   DISALLOW_COPY_AND_ASSIGN(SinkStream);
 174 };
 175
 176 // A SourceStreamSet is a set of SourceStreams.
 177 class SourceStreamSet {
 178  public:
 179   SourceStreamSet();
 180   ~SourceStreamSet();
 181
 182   // Initializes the SourceStreamSet with the stream data in memory at |source|.
 183   // The caller continues to own the memory and should not modify or free the
 184   // memory until the SourceStreamSet destructor has been called.
 185   //
 186   // The layout of the streams are as written by SinkStreamSet::CopyTo.
 187   // Init returns 'false' if the layout is inconsistent with |byte_count|.
 188   bool Init(const void* source, size_t byte_count);
 189
 190   // Initializes |this| from |source|.  The caller continues to own the memory
 191   // because it continues to be owned by |source|.
 192   bool Init(SourceStream* source);
 193
 194   // Returns a pointer to one of the sub-streams.
 195   SourceStream* stream(size_t id) { return id < count_ ? &streams_[id] : NULL; }
 196
 197   // Initialize |set| from |this|.
 198   bool ReadSet(SourceStreamSet* set);
 199
 200   // Returns 'true' if all streams are completely consumed.
 201   bool Empty() const;
 202
 203  private:
 204   size_t count_;
 205   SourceStream streams_[kMaxStreams];
 206
 207   DISALLOW_COPY_AND_ASSIGN(SourceStreamSet);
 208 };
 209
 210 // A SinkStreamSet is a set of SinkStreams.  Data is collected by writing to the
 211 // component streams.  When data collection is complete, it is destructively
 212 // transferred, either by flattening into one stream (CopyTo), or transfering
 213 // data pairwise into another SinkStreamSet by calling that SinkStreamSet's
 214 // WriteSet method.
 215 class SinkStreamSet {
 216  public:
 217   SinkStreamSet();
 218   ~SinkStreamSet();
 219
 220   // Initializes the SinkStreamSet to have |stream_index_limit| streams.  Must
 221   // be <= kMaxStreams.  If Init is not called the default is has kMaxStream.
 222   void Init(size_t stream_index_limit);
 223
 224   // Returns a pointer to a substream.
 225   SinkStream* stream(size_t id) { return id < count_ ? &streams_[id] : NULL; }
 226
 227   // CopyTo serializes the streams in this SinkStreamSet into a single target
 228   // stream.  The serialized format may be re-read by initializing a
 229   // SourceStreamSet with a buffer containing the data.
 230   CheckBool CopyTo(SinkStream* combined_stream) WARN_UNUSED_RESULT;
 231
 232   // Writes the streams of |set| into the corresponding streams of |this|.
 233   // Stream zero first has some metadata written to it.  |set| becomes retired.
 234   // Partner to SourceStreamSet::ReadSet.
 235   CheckBool WriteSet(SinkStreamSet* set) WARN_UNUSED_RESULT;
 236
 237  private:
 238   CheckBool CopyHeaderTo(SinkStream* stream) WARN_UNUSED_RESULT;
 239
 240   size_t count_;
 241   SinkStream streams_[kMaxStreams];
 242
 243   DISALLOW_COPY_AND_ASSIGN(SinkStreamSet);
 244 };
 245
 246 }  // namespace courgette
 247
 248 #endif  // COURGETTE_STREAMS_H_