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 (at) 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. 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. 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(). 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. 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