/thirdparty/breakpad/third_party/protobuf/protobuf/src/google/protobuf/io/zero_copy_stream.h

http://github.com/tomahawk-player/tomahawk · C++ Header · 238 lines · 34 code · 21 blank · 183 comment · 0 complexity · bf5fc4671ccd0327c959ecee2608eab8 MD5 · raw file

  1. // Protocol Buffers - Google's data interchange format
  2. // Copyright 2008 Google Inc. All rights reserved.
  3. // http://code.google.com/p/protobuf/
  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. // Author: kenton@google.com (Kenton Varda)
  31. // Based on original Protocol Buffers design by
  32. // Sanjay Ghemawat, Jeff Dean, and others.
  33. //
  34. // This file contains the ZeroCopyInputStream and ZeroCopyOutputStream
  35. // interfaces, which represent abstract I/O streams to and from which
  36. // protocol buffers can be read and written. For a few simple
  37. // implementations of these interfaces, see zero_copy_stream_impl.h.
  38. //
  39. // These interfaces are different from classic I/O streams in that they
  40. // try to minimize the amount of data copying that needs to be done.
  41. // To accomplish this, responsibility for allocating buffers is moved to
  42. // the stream object, rather than being the responsibility of the caller.
  43. // So, the stream can return a buffer which actually points directly into
  44. // the final data structure where the bytes are to be stored, and the caller
  45. // can interact directly with that buffer, eliminating an intermediate copy
  46. // operation.
  47. //
  48. // As an example, consider the common case in which you are reading bytes
  49. // from an array that is already in memory (or perhaps an mmap()ed file).
  50. // With classic I/O streams, you would do something like:
  51. // char buffer[BUFFER_SIZE];
  52. // input->Read(buffer, BUFFER_SIZE);
  53. // DoSomething(buffer, BUFFER_SIZE);
  54. // Then, the stream basically just calls memcpy() to copy the data from
  55. // the array into your buffer. With a ZeroCopyInputStream, you would do
  56. // this instead:
  57. // const void* buffer;
  58. // int size;
  59. // input->Next(&buffer, &size);
  60. // DoSomething(buffer, size);
  61. // Here, no copy is performed. The input stream returns a pointer directly
  62. // into the backing array, and the caller ends up reading directly from it.
  63. //
  64. // If you want to be able to read the old-fashion way, you can create
  65. // a CodedInputStream or CodedOutputStream wrapping these objects and use
  66. // their ReadRaw()/WriteRaw() methods. These will, of course, add a copy
  67. // step, but Coded*Stream will handle buffering so at least it will be
  68. // reasonably efficient.
  69. //
  70. // ZeroCopyInputStream example:
  71. // // Read in a file and print its contents to stdout.
  72. // int fd = open("myfile", O_RDONLY);
  73. // ZeroCopyInputStream* input = new FileInputStream(fd);
  74. //
  75. // const void* buffer;
  76. // int size;
  77. // while (input->Next(&buffer, &size)) {
  78. // cout.write(buffer, size);
  79. // }
  80. //
  81. // delete input;
  82. // close(fd);
  83. //
  84. // ZeroCopyOutputStream example:
  85. // // Copy the contents of "infile" to "outfile", using plain read() for
  86. // // "infile" but a ZeroCopyOutputStream for "outfile".
  87. // int infd = open("infile", O_RDONLY);
  88. // int outfd = open("outfile", O_WRONLY);
  89. // ZeroCopyOutputStream* output = new FileOutputStream(outfd);
  90. //
  91. // void* buffer;
  92. // int size;
  93. // while (output->Next(&buffer, &size)) {
  94. // int bytes = read(infd, buffer, size);
  95. // if (bytes < size) {
  96. // // Reached EOF.
  97. // output->BackUp(size - bytes);
  98. // break;
  99. // }
  100. // }
  101. //
  102. // delete output;
  103. // close(infd);
  104. // close(outfd);
  105. #ifndef GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_H__
  106. #define GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_H__
  107. #include <string>
  108. #include <google/protobuf/stubs/common.h>
  109. namespace google {
  110. namespace protobuf {
  111. namespace io {
  112. // Defined in this file.
  113. class ZeroCopyInputStream;
  114. class ZeroCopyOutputStream;
  115. // Abstract interface similar to an input stream but designed to minimize
  116. // copying.
  117. class LIBPROTOBUF_EXPORT ZeroCopyInputStream {
  118. public:
  119. inline ZeroCopyInputStream() {}
  120. virtual ~ZeroCopyInputStream();
  121. // Obtains a chunk of data from the stream.
  122. //
  123. // Preconditions:
  124. // * "size" and "data" are not NULL.
  125. //
  126. // Postconditions:
  127. // * If the returned value is false, there is no more data to return or
  128. // an error occurred. All errors are permanent.
  129. // * Otherwise, "size" points to the actual number of bytes read and "data"
  130. // points to a pointer to a buffer containing these bytes.
  131. // * Ownership of this buffer remains with the stream, and the buffer
  132. // remains valid only until some other method of the stream is called
  133. // or the stream is destroyed.
  134. // * It is legal for the returned buffer to have zero size, as long
  135. // as repeatedly calling Next() eventually yields a buffer with non-zero
  136. // size.
  137. virtual bool Next(const void** data, int* size) = 0;
  138. // Backs up a number of bytes, so that the next call to Next() returns
  139. // data again that was already returned by the last call to Next(). This
  140. // is useful when writing procedures that are only supposed to read up
  141. // to a certain point in the input, then return. If Next() returns a
  142. // buffer that goes beyond what you wanted to read, you can use BackUp()
  143. // to return to the point where you intended to finish.
  144. //
  145. // Preconditions:
  146. // * The last method called must have been Next().
  147. // * count must be less than or equal to the size of the last buffer
  148. // returned by Next().
  149. //
  150. // Postconditions:
  151. // * The last "count" bytes of the last buffer returned by Next() will be
  152. // pushed back into the stream. Subsequent calls to Next() will return
  153. // the same data again before producing new data.
  154. virtual void BackUp(int count) = 0;
  155. // Skips a number of bytes. Returns false if the end of the stream is
  156. // reached or some input error occurred. In the end-of-stream case, the
  157. // stream is advanced to the end of the stream (so ByteCount() will return
  158. // the total size of the stream).
  159. virtual bool Skip(int count) = 0;
  160. // Returns the total number of bytes read since this object was created.
  161. virtual int64 ByteCount() const = 0;
  162. private:
  163. GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ZeroCopyInputStream);
  164. };
  165. // Abstract interface similar to an output stream but designed to minimize
  166. // copying.
  167. class LIBPROTOBUF_EXPORT ZeroCopyOutputStream {
  168. public:
  169. inline ZeroCopyOutputStream() {}
  170. virtual ~ZeroCopyOutputStream();
  171. // Obtains a buffer into which data can be written. Any data written
  172. // into this buffer will eventually (maybe instantly, maybe later on)
  173. // be written to the output.
  174. //
  175. // Preconditions:
  176. // * "size" and "data" are not NULL.
  177. //
  178. // Postconditions:
  179. // * If the returned value is false, an error occurred. All errors are
  180. // permanent.
  181. // * Otherwise, "size" points to the actual number of bytes in the buffer
  182. // and "data" points to the buffer.
  183. // * Ownership of this buffer remains with the stream, and the buffer
  184. // remains valid only until some other method of the stream is called
  185. // or the stream is destroyed.
  186. // * Any data which the caller stores in this buffer will eventually be
  187. // written to the output (unless BackUp() is called).
  188. // * It is legal for the returned buffer to have zero size, as long
  189. // as repeatedly calling Next() eventually yields a buffer with non-zero
  190. // size.
  191. virtual bool Next(void** data, int* size) = 0;
  192. // Backs up a number of bytes, so that the end of the last buffer returned
  193. // by Next() is not actually written. This is needed when you finish
  194. // writing all the data you want to write, but the last buffer was bigger
  195. // than you needed. You don't want to write a bunch of garbage after the
  196. // end of your data, so you use BackUp() to back up.
  197. //
  198. // Preconditions:
  199. // * The last method called must have been Next().
  200. // * count must be less than or equal to the size of the last buffer
  201. // returned by Next().
  202. // * The caller must not have written anything to the last "count" bytes
  203. // of that buffer.
  204. //
  205. // Postconditions:
  206. // * The last "count" bytes of the last buffer returned by Next() will be
  207. // ignored.
  208. virtual void BackUp(int count) = 0;
  209. // Returns the total number of bytes written since this object was created.
  210. virtual int64 ByteCount() const = 0;
  211. private:
  212. GOOGLE_DISALLOW_EVIL_CONSTRUCTORS(ZeroCopyOutputStream);
  213. };
  214. } // namespace io
  215. } // namespace protobuf
  216. } // namespace google
  217. #endif // GOOGLE_PROTOBUF_IO_ZERO_COPY_STREAM_H__