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