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/stl_util.h>
57
58
59 namespace google {
60 namespace protobuf {
61 namespace io {
62
63 // ===================================================================
64
65 // A ZeroCopyInputStream backed by an in-memory array of bytes.
66 class LIBPROTOBUF_EXPORT ArrayInputStream : public ZeroCopyInputStream {
67 public:
68 // Create an InputStream that returns the bytes pointed to by "data".
69 // "data" remains the property of the caller but must remain valid until
70 // the stream is destroyed. If a block_size is given, calls to Next()
71 // will return data blocks no larger than the given size. Otherwise, the
72 // first call to Next() returns the entire array. block_size is mainly
73 // useful for testing; in production you would probably never want to set
74 // it.
75 ArrayInputStream(const void* data, int size, int block_size = -1);
76
77 // implements ZeroCopyInputStream ----------------------------------
78 bool Next(const void** data, int* size);
79 void BackUp(int count);
80 bool Skip(int count);
81 int64 ByteCount() const;
82
83
84 private:
85 const uint8* const data_; // The byte array.
86 const int size_; // Total size of the array.
87 const int block_size_; // How many bytes to return at a time.
88
89 int position_;
90 int last_returned_size_; // How many bytes we returned last time Next()
91 // was called (used for error checking only).
92
93 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayInputStream);
94 };
95
96 // ===================================================================
97
98 // A ZeroCopyOutputStream backed by an in-memory array of bytes.
99 class LIBPROTOBUF_EXPORT ArrayOutputStream : public ZeroCopyOutputStream {
100 public:
101 // Create an OutputStream that writes to the bytes pointed to by "data".
102 // "data" remains the property of the caller but must remain valid until
103 // the stream is destroyed. If a block_size is given, calls to Next()
104 // will return data blocks no larger than the given size. Otherwise, the
105 // first call to Next() returns the entire array. block_size is mainly
106 // useful for testing; in production you would probably never want to set
107 // it.
108 ArrayOutputStream(void* data, int size, int block_size = -1);
109
110 // implements ZeroCopyOutputStream ---------------------------------
111 bool Next(void** data, int* size);
112 void BackUp(int count);
113 int64 ByteCount() const;
114
115 private:
116 uint8* const data_; // The byte array.
117 const int size_; // Total size of the array.
118 const int block_size_; // How many bytes to return at a time.
119
120 int position_;
121 int last_returned_size_; // How many bytes we returned last time Next()
122 // was called (used for error checking only).
123
124 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ArrayOutputStream);
125 };
126
127 // ===================================================================
128
129 // A ZeroCopyOutputStream which appends bytes to a string.
130 class LIBPROTOBUF_EXPORT StringOutputStream : public ZeroCopyOutputStream {
131 public:
132 // Create a StringOutputStream which appends bytes to the given string.
133 // The string remains property of the caller, but it is mutated in arbitrary
134 // ways and MUST NOT be accessed in any way until you're done with the
135 // stream. Either be sure there's no further usage, or (safest) destroy the
136 // stream before using the contents.
137 //
138 // Hint: If you call target->reserve(n) before creating the stream,
139 // the first call to Next() will return at least n bytes of buffer
140 // space.
141 explicit StringOutputStream(string* target);
142
143 // implements ZeroCopyOutputStream ---------------------------------
144 bool Next(void** data, int* size);
145 void BackUp(int count);
146 int64 ByteCount() const;
147
148 protected:
149 void SetString(string* target);
150
151 private:
152 static const int kMinimumSize = 16;
153
154 string* target_;
155
156 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(StringOutputStream);
157 };
158
159 // Note: There is no StringInputStream. Instead, just create an
160 // ArrayInputStream as follows:
161 // ArrayInputStream input(str.data(), str.size());
162
163 // ===================================================================
164
165 // A generic traditional input stream interface.
166 //
167 // Lots of traditional input streams (e.g. file descriptors, C stdio
168 // streams, and C++ iostreams) expose an interface where every read
169 // involves copying bytes into a buffer. If you want to take such an
170 // interface and make a ZeroCopyInputStream based on it, simply implement
171 // CopyingInputStream and then use CopyingInputStreamAdaptor.
172 //
173 // CopyingInputStream implementations should avoid buffering if possible.
174 // CopyingInputStreamAdaptor does its own buffering and will read data
175 // in large blocks.
176 class LIBPROTOBUF_EXPORT CopyingInputStream {
177 public:
~CopyingInputStream()178 virtual ~CopyingInputStream() {}
179
180 // Reads up to "size" bytes into the given buffer. Returns the number of
181 // bytes read. Read() waits until at least one byte is available, or
182 // returns zero if no bytes will ever become available (EOF), or -1 if a
183 // permanent read error occurred.
184 virtual int Read(void* buffer, int size) = 0;
185
186 // Skips the next "count" bytes of input. Returns the number of bytes
187 // actually skipped. This will always be exactly equal to "count" unless
188 // EOF was reached or a permanent read error occurred.
189 //
190 // The default implementation just repeatedly calls Read() into a scratch
191 // buffer.
192 virtual int Skip(int count);
193 };
194
195 // A ZeroCopyInputStream which reads from a CopyingInputStream. This is
196 // useful for implementing ZeroCopyInputStreams that read from traditional
197 // streams. Note that this class is not really zero-copy.
198 //
199 // If you want to read from file descriptors or C++ istreams, this is
200 // already implemented for you: use FileInputStream or IstreamInputStream
201 // respectively.
202 class LIBPROTOBUF_EXPORT CopyingInputStreamAdaptor : public ZeroCopyInputStream {
203 public:
204 // Creates a stream that reads from the given CopyingInputStream.
205 // If a block_size is given, it specifies the number of bytes that
206 // should be read and returned with each call to Next(). Otherwise,
207 // a reasonable default is used. The caller retains ownership of
208 // copying_stream unless SetOwnsCopyingStream(true) is called.
209 explicit CopyingInputStreamAdaptor(CopyingInputStream* copying_stream,
210 int block_size = -1);
211 ~CopyingInputStreamAdaptor();
212
213 // Call SetOwnsCopyingStream(true) to tell the CopyingInputStreamAdaptor to
214 // delete the underlying CopyingInputStream when it is destroyed.
SetOwnsCopyingStream(bool value)215 void SetOwnsCopyingStream(bool value) { owns_copying_stream_ = value; }
216
217 // implements ZeroCopyInputStream ----------------------------------
218 bool Next(const void** data, int* size);
219 void BackUp(int count);
220 bool Skip(int count);
221 int64 ByteCount() const;
222
223 private:
224 // Insures that buffer_ is not NULL.
225 void AllocateBufferIfNeeded();
226 // Frees the buffer and resets buffer_used_.
227 void FreeBuffer();
228
229 // The underlying copying stream.
230 CopyingInputStream* copying_stream_;
231 bool owns_copying_stream_;
232
233 // True if we have seen a permenant error from the underlying stream.
234 bool failed_;
235
236 // The current position of copying_stream_, relative to the point where
237 // we started reading.
238 int64 position_;
239
240 // Data is read into this buffer. It may be NULL if no buffer is currently
241 // in use. Otherwise, it points to an array of size buffer_size_.
242 google::protobuf::scoped_array<uint8> buffer_;
243 const int buffer_size_;
244
245 // Number of valid bytes currently in the buffer (i.e. the size last
246 // returned by Next()). 0 <= buffer_used_ <= buffer_size_.
247 int buffer_used_;
248
249 // Number of bytes in the buffer which were backed up over by a call to
250 // BackUp(). These need to be returned again.
251 // 0 <= backup_bytes_ <= buffer_used_
252 int backup_bytes_;
253
254 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CopyingInputStreamAdaptor);
255 };
256
257 // ===================================================================
258
259 // A generic traditional output stream interface.
260 //
261 // Lots of traditional output streams (e.g. file descriptors, C stdio
262 // streams, and C++ iostreams) expose an interface where every write
263 // involves copying bytes from a buffer. If you want to take such an
264 // interface and make a ZeroCopyOutputStream based on it, simply implement
265 // CopyingOutputStream and then use CopyingOutputStreamAdaptor.
266 //
267 // CopyingOutputStream implementations should avoid buffering if possible.
268 // CopyingOutputStreamAdaptor does its own buffering and will write data
269 // in large blocks.
270 class LIBPROTOBUF_EXPORT CopyingOutputStream {
271 public:
~CopyingOutputStream()272 virtual ~CopyingOutputStream() {}
273
274 // Writes "size" bytes from the given buffer to the output. Returns true
275 // if successful, false on a write error.
276 virtual bool Write(const void* buffer, int size) = 0;
277 };
278
279 // A ZeroCopyOutputStream which writes to a CopyingOutputStream. This is
280 // useful for implementing ZeroCopyOutputStreams that write to traditional
281 // streams. Note that this class is not really zero-copy.
282 //
283 // If you want to write to file descriptors or C++ ostreams, this is
284 // already implemented for you: use FileOutputStream or OstreamOutputStream
285 // respectively.
286 class LIBPROTOBUF_EXPORT CopyingOutputStreamAdaptor : public ZeroCopyOutputStream {
287 public:
288 // Creates a stream that writes to the given Unix file descriptor.
289 // If a block_size is given, it specifies the size of the buffers
290 // that should be returned by Next(). Otherwise, a reasonable default
291 // is used.
292 explicit CopyingOutputStreamAdaptor(CopyingOutputStream* copying_stream,
293 int block_size = -1);
294 ~CopyingOutputStreamAdaptor();
295
296 // Writes all pending data to the underlying stream. Returns false if a
297 // write error occurred on the underlying stream. (The underlying
298 // stream itself is not necessarily flushed.)
299 bool Flush();
300
301 // Call SetOwnsCopyingStream(true) to tell the CopyingOutputStreamAdaptor to
302 // delete the underlying CopyingOutputStream when it is destroyed.
SetOwnsCopyingStream(bool value)303 void SetOwnsCopyingStream(bool value) { owns_copying_stream_ = value; }
304
305 // implements ZeroCopyOutputStream ---------------------------------
306 bool Next(void** data, int* size);
307 void BackUp(int count);
308 int64 ByteCount() const;
309
310 private:
311 // Write the current buffer, if it is present.
312 bool WriteBuffer();
313 // Insures that buffer_ is not NULL.
314 void AllocateBufferIfNeeded();
315 // Frees the buffer.
316 void FreeBuffer();
317
318 // The underlying copying stream.
319 CopyingOutputStream* copying_stream_;
320 bool owns_copying_stream_;
321
322 // True if we have seen a permenant error from the underlying stream.
323 bool failed_;
324
325 // The current position of copying_stream_, relative to the point where
326 // we started writing.
327 int64 position_;
328
329 // Data is written from this buffer. It may be NULL if no buffer is
330 // currently in use. Otherwise, it points to an array of size buffer_size_.
331 google::protobuf::scoped_array<uint8> buffer_;
332 const int buffer_size_;
333
334 // Number of valid bytes currently in the buffer (i.e. the size last
335 // returned by Next()). When BackUp() is called, we just reduce this.
336 // 0 <= buffer_used_ <= buffer_size_.
337 int buffer_used_;
338
339 GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(CopyingOutputStreamAdaptor);
340 };
341
342 // ===================================================================
343
344 // mutable_string_data() and as_string_data() are workarounds to improve
345 // the performance of writing new data to an existing string. Unfortunately
346 // the methods provided by the string class are suboptimal, and using memcpy()
347 // is mildly annoying because it requires its pointer args to be non-NULL even
348 // if we ask it to copy 0 bytes. Furthermore, string_as_array() has the
349 // property that it always returns NULL if its arg is the empty string, exactly
350 // what we want to avoid if we're using it in conjunction with memcpy()!
351 // With C++11, the desired memcpy() boils down to memcpy(..., &(*s)[0], size),
352 // where s is a string*. Without C++11, &(*s)[0] is not guaranteed to be safe,
353 // so we use string_as_array(), and live with the extra logic that tests whether
354 // *s is empty.
355
356 // Return a pointer to mutable characters underlying the given string. The
357 // return value is valid until the next time the string is resized. We
358 // trust the caller to treat the return value as an array of length s->size().
mutable_string_data(string * s)359 inline char* mutable_string_data(string* s) {
360 #ifdef LANG_CXX11
361 // This should be simpler & faster than string_as_array() because the latter
362 // is guaranteed to return NULL when *s is empty, so it has to check for that.
363 return &(*s)[0];
364 #else
365 return string_as_array(s);
366 #endif
367 }
368
369 // as_string_data(s) is equivalent to
370 // ({ char* p = mutable_string_data(s); make_pair(p, p != NULL); })
371 // Sometimes it's faster: in some scenarios p cannot be NULL, and then the
372 // code can avoid that check.
as_string_data(string * s)373 inline std::pair<char*, bool> as_string_data(string* s) {
374 char *p = mutable_string_data(s);
375 #ifdef LANG_CXX11
376 return std::make_pair(p, true);
377 #else
378 return std::make_pair(p, p != NULL);
379 #endif
380 }
381
382 } // namespace io
383 } // namespace protobuf
384
385 } // namespace google
386 #endif // GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_IMPL_LITE_H__
387