• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 // Protocol Buffers - Google's data interchange format
2 // Copyright 2008 Google Inc.  All rights reserved.
3 // https://developers.google.com/protocol-buffers/
4 //
5 // Redistribution and use in source and binary forms, with or without
6 // modification, are permitted provided that the following conditions are
7 // met:
8 //
9 //     * Redistributions of source code must retain the above copyright
10 // notice, this list of conditions and the following disclaimer.
11 //     * Redistributions in binary form must reproduce the above
12 // copyright notice, this list of conditions and the following disclaimer
13 // in the documentation and/or other materials provided with the
14 // distribution.
15 //     * Neither the name of Google Inc. nor the names of its
16 // contributors may be used to endorse or promote products derived from
17 // this software without specific prior written permission.
18 //
19 // THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 // "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 // LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22 // A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 // OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24 // SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25 // LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26 // DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27 // THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 
31 // Author: kenton@google.com (Kenton Varda)
32 //  Based on original Protocol Buffers design by
33 //  Sanjay Ghemawat, Jeff Dean, and others.
34 //
35 // This file contains common implementations of the interfaces defined in
36 // zero_copy_stream.h which are included in the "lite" protobuf library.
37 // These implementations cover I/O on raw arrays and strings, as well as
38 // adaptors which make it easy to implement streams based on traditional
39 // streams.  Of course, many users will probably want to write their own
40 // implementations of these interfaces specific to the particular I/O
41 // abstractions they prefer to use, but these should cover the most common
42 // cases.
43 
44 #ifndef GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
45 #define GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
46 
47 #include <memory>
48 #ifndef _SHARED_PTR_H
49 #include <google/protobuf/stubs/shared_ptr.h>
50 #endif
51 #include <string>
52 #include <iosfwd>
53 #include <google/protobuf/io/zero_copy_stream.h>
54 #include <google/protobuf/stubs/callback.h>
55 #include <google/protobuf/stubs/common.h>
56 #include <google/protobuf/stubs/scoped_ptr.h>
57 #include <google/protobuf/stubs/stl_util.h>
58 
59 
60 namespace google {
61 namespace protobuf {
62 namespace io {
63 
64 // ===================================================================
65 
66 // A ZeroCopyInputStream backed by an in-memory array of bytes.
67 class LIBPROTOBUF_EXPORT ArrayInputStream : public ZeroCopyInputStream {
68  public:
69   // Create an InputStream that returns the bytes pointed to by "data".
70   // "data" remains the property of the caller but must remain valid until
71   // the stream is destroyed.  If a block_size is given, calls to Next()
72   // will return data blocks no larger than the given size.  Otherwise, the
73   // first call to Next() returns the entire array.  block_size is mainly
74   // useful for testing; in production you would probably never want to set
75   // it.
76   ArrayInputStream(const void* data, int size, int block_size = -1);
77   ~ArrayInputStream();
78 
79   // implements ZeroCopyInputStream ----------------------------------
80   bool Next(const void** data, int* size);
81   void BackUp(int count);
82   bool Skip(int count);
83   int64 ByteCount() const;
84 
85 
86  private:
87   const uint8* const data_;  // The byte array.
88   const int size_;           // Total size of the array.
89   const int block_size_;     // How many bytes to return at a time.
90 
91   int position_;
92   int last_returned_size_;   // How many bytes we returned last time Next()
93                              // was called (used for error checking only).
94 
95   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayInputStream);
96 };
97 
98 // ===================================================================
99 
100 // A ZeroCopyOutputStream backed by an in-memory array of bytes.
101 class LIBPROTOBUF_EXPORT ArrayOutputStream : public ZeroCopyOutputStream {
102  public:
103   // Create an OutputStream that writes to the bytes pointed to by "data".
104   // "data" remains the property of the caller but must remain valid until
105   // the stream is destroyed.  If a block_size is given, calls to Next()
106   // will return data blocks no larger than the given size.  Otherwise, the
107   // first call to Next() returns the entire array.  block_size is mainly
108   // useful for testing; in production you would probably never want to set
109   // it.
110   ArrayOutputStream(void* data, int size, int block_size = -1);
111   ~ArrayOutputStream();
112 
113   // implements ZeroCopyOutputStream ---------------------------------
114   bool Next(void** data, int* size);
115   void BackUp(int count);
116   int64 ByteCount() const;
117 
118  private:
119   uint8* const data_;        // The byte array.
120   const int size_;           // Total size of the array.
121   const int block_size_;     // How many bytes to return at a time.
122 
123   int position_;
124   int last_returned_size_;   // How many bytes we returned last time Next()
125                              // was called (used for error checking only).
126 
127   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayOutputStream);
128 };
129 
130 // ===================================================================
131 
132 // A ZeroCopyOutputStream which appends bytes to a string.
133 class LIBPROTOBUF_EXPORT StringOutputStream : public ZeroCopyOutputStream {
134  public:
135   // Create a StringOutputStream which appends bytes to the given string.
136   // The string remains property of the caller, but it is mutated in arbitrary
137   // ways and MUST NOT be accessed in any way until you're done with the
138   // stream. Either be sure there's no further usage, or (safest) destroy the
139   // stream before using the contents.
140   //
141   // Hint:  If you call target->reserve(n) before creating the stream,
142   //   the first call to Next() will return at least n bytes of buffer
143   //   space.
144   explicit StringOutputStream(string* target);
145   ~StringOutputStream();
146 
147   // implements ZeroCopyOutputStream ---------------------------------
148   bool Next(void** data, int* size);
149   void BackUp(int count);
150   int64 ByteCount() const;
151 
152  protected:
153   void SetString(string* target);
154 
155  private:
156   static const int kMinimumSize = 16;
157 
158   string* target_;
159 
160   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(StringOutputStream);
161 };
162 
163 // LazyStringOutputStream is a StringOutputStream with lazy acquisition of
164 // the output string from a callback. The string is owned externally, and not
165 // deleted in the stream destructor.
166 class LIBPROTOBUF_EXPORT LazyStringOutputStream : public StringOutputStream {
167  public:
168   // Callback should be permanent (non-self-deleting). Ownership is transferred
169   // to the LazyStringOutputStream.
170   explicit LazyStringOutputStream(ResultCallback<string*>* callback);
171   ~LazyStringOutputStream();
172 
173   // implements ZeroCopyOutputStream, overriding StringOutputStream -----------
174   bool Next(void** data, int* size);
175   int64 ByteCount() const;
176 
177  private:
178   const google::protobuf::scoped_ptr<ResultCallback<string*> > callback_;
179   bool string_is_set_;
180 
181   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(LazyStringOutputStream);
182 };
183 
184 // Note:  There is no StringInputStream.  Instead, just create an
185 // ArrayInputStream as follows:
186 //   ArrayInputStream input(str.data(), str.size());
187 
188 // ===================================================================
189 
190 // A generic traditional input stream interface.
191 //
192 // Lots of traditional input streams (e.g. file descriptors, C stdio
193 // streams, and C++ iostreams) expose an interface where every read
194 // involves copying bytes into a buffer.  If you want to take such an
195 // interface and make a ZeroCopyInputStream based on it, simply implement
196 // CopyingInputStream and then use CopyingInputStreamAdaptor.
197 //
198 // CopyingInputStream implementations should avoid buffering if possible.
199 // CopyingInputStreamAdaptor does its own buffering and will read data
200 // in large blocks.
201 class LIBPROTOBUF_EXPORT CopyingInputStream {
202  public:
203   virtual ~CopyingInputStream();
204 
205   // Reads up to "size" bytes into the given buffer.  Returns the number of
206   // bytes read.  Read() waits until at least one byte is available, or
207   // returns zero if no bytes will ever become available (EOF), or -1 if a
208   // permanent read error occurred.
209   virtual int Read(void* buffer, int size) = 0;
210 
211   // Skips the next "count" bytes of input.  Returns the number of bytes
212   // actually skipped.  This will always be exactly equal to "count" unless
213   // EOF was reached or a permanent read error occurred.
214   //
215   // The default implementation just repeatedly calls Read() into a scratch
216   // buffer.
217   virtual int Skip(int count);
218 };
219 
220 // A ZeroCopyInputStream which reads from a CopyingInputStream.  This is
221 // useful for implementing ZeroCopyInputStreams that read from traditional
222 // streams.  Note that this class is not really zero-copy.
223 //
224 // If you want to read from file descriptors or C++ istreams, this is
225 // already implemented for you:  use FileInputStream or IstreamInputStream
226 // respectively.
227 class LIBPROTOBUF_EXPORT CopyingInputStreamAdaptor : public ZeroCopyInputStream {
228  public:
229   // Creates a stream that reads from the given CopyingInputStream.
230   // If a block_size is given, it specifies the number of bytes that
231   // should be read and returned with each call to Next().  Otherwise,
232   // a reasonable default is used.  The caller retains ownership of
233   // copying_stream unless SetOwnsCopyingStream(true) is called.
234   explicit CopyingInputStreamAdaptor(CopyingInputStream* copying_stream,
235                                      int block_size = -1);
236   ~CopyingInputStreamAdaptor();
237 
238   // Call SetOwnsCopyingStream(true) to tell the CopyingInputStreamAdaptor to
239   // delete the underlying CopyingInputStream when it is destroyed.
SetOwnsCopyingStream(bool value)240   void SetOwnsCopyingStream(bool value) { owns_copying_stream_ = value; }
241 
242   // implements ZeroCopyInputStream ----------------------------------
243   bool Next(const void** data, int* size);
244   void BackUp(int count);
245   bool Skip(int count);
246   int64 ByteCount() const;
247 
248  private:
249   // Insures that buffer_ is not NULL.
250   void AllocateBufferIfNeeded();
251   // Frees the buffer and resets buffer_used_.
252   void FreeBuffer();
253 
254   // The underlying copying stream.
255   CopyingInputStream* copying_stream_;
256   bool owns_copying_stream_;
257 
258   // True if we have seen a permenant error from the underlying stream.
259   bool failed_;
260 
261   // The current position of copying_stream_, relative to the point where
262   // we started reading.
263   int64 position_;
264 
265   // Data is read into this buffer.  It may be NULL if no buffer is currently
266   // in use.  Otherwise, it points to an array of size buffer_size_.
267   google::protobuf::scoped_array<uint8> buffer_;
268   const int buffer_size_;
269 
270   // Number of valid bytes currently in the buffer (i.e. the size last
271   // returned by Next()).  0 <= buffer_used_ <= buffer_size_.
272   int buffer_used_;
273 
274   // Number of bytes in the buffer which were backed up over by a call to
275   // BackUp().  These need to be returned again.
276   // 0 <= backup_bytes_ <= buffer_used_
277   int backup_bytes_;
278 
279   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CopyingInputStreamAdaptor);
280 };
281 
282 // ===================================================================
283 
284 // A generic traditional output stream interface.
285 //
286 // Lots of traditional output streams (e.g. file descriptors, C stdio
287 // streams, and C++ iostreams) expose an interface where every write
288 // involves copying bytes from a buffer.  If you want to take such an
289 // interface and make a ZeroCopyOutputStream based on it, simply implement
290 // CopyingOutputStream and then use CopyingOutputStreamAdaptor.
291 //
292 // CopyingOutputStream implementations should avoid buffering if possible.
293 // CopyingOutputStreamAdaptor does its own buffering and will write data
294 // in large blocks.
295 class LIBPROTOBUF_EXPORT CopyingOutputStream {
296  public:
297   virtual ~CopyingOutputStream();
298 
299   // Writes "size" bytes from the given buffer to the output.  Returns true
300   // if successful, false on a write error.
301   virtual bool Write(const void* buffer, int size) = 0;
302 };
303 
304 // A ZeroCopyOutputStream which writes to a CopyingOutputStream.  This is
305 // useful for implementing ZeroCopyOutputStreams that write to traditional
306 // streams.  Note that this class is not really zero-copy.
307 //
308 // If you want to write to file descriptors or C++ ostreams, this is
309 // already implemented for you:  use FileOutputStream or OstreamOutputStream
310 // respectively.
311 class LIBPROTOBUF_EXPORT CopyingOutputStreamAdaptor : public ZeroCopyOutputStream {
312  public:
313   // Creates a stream that writes to the given Unix file descriptor.
314   // If a block_size is given, it specifies the size of the buffers
315   // that should be returned by Next().  Otherwise, a reasonable default
316   // is used.
317   explicit CopyingOutputStreamAdaptor(CopyingOutputStream* copying_stream,
318                                       int block_size = -1);
319   ~CopyingOutputStreamAdaptor();
320 
321   // Writes all pending data to the underlying stream.  Returns false if a
322   // write error occurred on the underlying stream.  (The underlying
323   // stream itself is not necessarily flushed.)
324   bool Flush();
325 
326   // Call SetOwnsCopyingStream(true) to tell the CopyingOutputStreamAdaptor to
327   // delete the underlying CopyingOutputStream when it is destroyed.
SetOwnsCopyingStream(bool value)328   void SetOwnsCopyingStream(bool value) { owns_copying_stream_ = value; }
329 
330   // implements ZeroCopyOutputStream ---------------------------------
331   bool Next(void** data, int* size);
332   void BackUp(int count);
333   int64 ByteCount() const;
334 
335  private:
336   // Write the current buffer, if it is present.
337   bool WriteBuffer();
338   // Insures that buffer_ is not NULL.
339   void AllocateBufferIfNeeded();
340   // Frees the buffer.
341   void FreeBuffer();
342 
343   // The underlying copying stream.
344   CopyingOutputStream* copying_stream_;
345   bool owns_copying_stream_;
346 
347   // True if we have seen a permenant error from the underlying stream.
348   bool failed_;
349 
350   // The current position of copying_stream_, relative to the point where
351   // we started writing.
352   int64 position_;
353 
354   // Data is written from this buffer.  It may be NULL if no buffer is
355   // currently in use.  Otherwise, it points to an array of size buffer_size_.
356   google::protobuf::scoped_array<uint8> buffer_;
357   const int buffer_size_;
358 
359   // Number of valid bytes currently in the buffer (i.e. the size last
360   // returned by Next()).  When BackUp() is called, we just reduce this.
361   // 0 <= buffer_used_ <= buffer_size_.
362   int buffer_used_;
363 
364   GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CopyingOutputStreamAdaptor);
365 };
366 
367 // ===================================================================
368 
369 // mutable_string_data() and as_string_data() are workarounds to improve
370 // the performance of writing new data to an existing string.  Unfortunately
371 // the methods provided by the string class are suboptimal, and using memcpy()
372 // is mildly annoying because it requires its pointer args to be non-NULL even
373 // if we ask it to copy 0 bytes.  Furthermore, string_as_array() has the
374 // property that it always returns NULL if its arg is the empty string, exactly
375 // what we want to avoid if we're using it in conjunction with memcpy()!
376 // With C++11, the desired memcpy() boils down to memcpy(..., &(*s)[0], size),
377 // where s is a string*.  Without C++11, &(*s)[0] is not guaranteed to be safe,
378 // so we use string_as_array(), and live with the extra logic that tests whether
379 // *s is empty.
380 
381 // Return a pointer to mutable characters underlying the given string.  The
382 // return value is valid until the next time the string is resized.  We
383 // trust the caller to treat the return value as an array of length s->size().
mutable_string_data(string * s)384 inline char* mutable_string_data(string* s) {
385 #ifdef LANG_CXX11
386   // This should be simpler & faster than string_as_array() because the latter
387   // is guaranteed to return NULL when *s is empty, so it has to check for that.
388   return &(*s)[0];
389 #else
390   return string_as_array(s);
391 #endif
392 }
393 
394 // as_string_data(s) is equivalent to
395 //  ({ char* p = mutable_string_data(s); make_pair(p, p != NULL); })
396 // Sometimes it's faster: in some scenarios p cannot be NULL, and then the
397 // code can avoid that check.
as_string_data(string * s)398 inline std::pair<char*, bool> as_string_data(string* s) {
399   char *p = mutable_string_data(s);
400 #ifdef LANG_CXX11
401   return std::make_pair(p, true);
402 #else
403   return make_pair(p, p != NULL);
404 #endif
405 }
406 
407 }  // namespace io
408 }  // namespace protobuf
409 
410 }  // namespace google
411 #endif  // GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
412