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

source code of include/google/protobuf/io/zero_copy_stream_impl_lite.h