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