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