zero_copy_stream_iml_lite.h
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
This file contains common implementations of the interfaces defined in zero_copy_stream.h which are included in the "lite" protobuf library.
These implementations cover I/O on raw arrays and strings, as well as adaptors which make it easy to implement streams based on traditional streams. Of course, many users will probably want to write their own implementations of these interfaces specific to the particular I/O abstractions they prefer to use, but these should cover the most common cases.
Classes in this file | |
|---|---|
A ZeroCopyInputStream backed by an in-memory array of bytes. | |
A ZeroCopyOutputStream backed by an in-memory array of bytes. | |
A ZeroCopyOutputStream which appends bytes to a string. | |
A generic traditional input stream interface. | |
A ZeroCopyInputStream which reads from a CopyingInputStream. | |
A generic traditional output stream interface. | |
A ZeroCopyOutputStream which writes to a CopyingOutputStream. | |
A ZeroCopyInputStream which wraps some other stream and limits it to a particular byte count. | |
File MembersThese definitions are not part of any class. | |
|---|---|
char * | mutable_string_data(std::string * s)Return a pointer to mutable characters underlying the given string. more... |
std::pair< char *, bool > | as_string_data(std::string * s)as_string_data(s) is equivalent to ({ char* p = mutable_string_data(s); make_pair(p, p != NULL); }) Sometimes it's faster: in some scenarios p cannot be NULL, and then the code can avoid that check. |
char * io::mutable_string_data(
std::string * s)
std::string * s)
Return a pointer to mutable characters underlying the given string.
The return value is valid until the next time the string is resized. We trust the caller to treat the return value as an array of length s->size().
class ArrayInputStream: public ZeroCopyInputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyInputStream backed by an in-memory array of bytes.
Members | |
|---|---|
| ArrayInputStream(const void * data, int size, int block_size = -1)Create an InputStream that returns the bytes pointed to by "data". more... |
| ~ArrayInputStream() |
implements ZeroCopyInputStream | |
virtual bool | Next(const void ** data, int * size)Obtains a chunk of data from the stream. more... |
virtual void | BackUp(int count) |
virtual bool | Skip(int count)Skips a number of bytes. more... |
virtual int64_t | ByteCount() constReturns the total number of bytes read since this object was created. |
ArrayInputStream::ArrayInputStream(
const void * data,
int size,
int block_size = -1)
const void * data,
int size,
int block_size = -1)
Create an InputStream that returns the bytes pointed to by "data".
"data" remains the property of the caller but must remain valid until the stream is destroyed. If a block_size is given, calls to Next() will return data blocks no larger than the given size. Otherwise, the first call to Next() returns the entire array. block_size is mainly useful for testing; in production you would probably never want to set it.
virtual bool ArrayInputStream::Next(
const void ** data,
int * size)
const void ** data,
int * size)
Obtains a chunk of data from the stream.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, there is no more data to return or an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes read and "data" points to a pointer to a buffer containing these bytes.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void ArrayInputStream::BackUp(
int count)
int count)
Backs up a number of bytes, so that the next call to Next() returns data again that was already returned by the last call to Next().
This is useful when writing procedures that are only supposed to read up to a certain point in the input, then return. If Next() returns a buffer that goes beyond what you wanted to read, you can use BackUp() to return to the point where you intended to finish.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
Postconditions:
virtual bool ArrayInputStream::Skip(
int count)
int count)
Skips a number of bytes.
Returns false if the end of the stream is reached or some input error occurred. In the end-of-stream case, the stream is advanced to the end of the stream (so ByteCount() will return the total size of the stream).
class ArrayOutputStream: public ZeroCopyOutputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyOutputStream backed by an in-memory array of bytes.
Members | |
|---|---|
| ArrayOutputStream(void * data, int size, int block_size = -1)Create an OutputStream that writes to the bytes pointed to by "data". more... |
| ~ArrayOutputStream() |
implements ZeroCopyOutputStream | |
virtual bool | Next(void ** data, int * size)Obtains a buffer into which data can be written. more... |
virtual void | BackUp(int count) |
virtual int64_t | ByteCount() constReturns the total number of bytes written since this object was created. |
ArrayOutputStream::ArrayOutputStream(
void * data,
int size,
int block_size = -1)
void * data,
int size,
int block_size = -1)
Create an OutputStream that writes to the bytes pointed to by "data".
"data" remains the property of the caller but must remain valid until the stream is destroyed. If a block_size is given, calls to Next() will return data blocks no larger than the given size. Otherwise, the first call to Next() returns the entire array. block_size is mainly useful for testing; in production you would probably never want to set it.
virtual bool ArrayOutputStream::Next(
void ** data,
int * size)
void ** data,
int * size)
Obtains a buffer into which data can be written.
Any data written into this buffer will eventually (maybe instantly, maybe later on) be written to the output.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes in the buffer and "data" points to the buffer.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- Any data which the caller stores in this buffer will eventually be written to the output (unless BackUp() is called).
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void ArrayOutputStream::BackUp(
int count)
int count)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written.
This is needed when you finish writing all the data you want to write, but the last buffer was bigger than you needed. You don't want to write a bunch of garbage after the end of your data, so you use BackUp() to back up.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
- The caller must not have written anything to the last "count" bytes of that buffer.
Postconditions:
- The last "count" bytes of the last buffer returned by Next() will be ignored.
class StringOutputStream: public ZeroCopyOutputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyOutputStream which appends bytes to a string.
Members | |
|---|---|
explicit | StringOutputStream(std::string * target)Create a StringOutputStream which appends bytes to the given string. more... |
| ~StringOutputStream() |
implements ZeroCopyOutputStream | |
virtual bool | Next(void ** data, int * size)Obtains a buffer into which data can be written. more... |
virtual void | BackUp(int count) |
virtual int64_t | ByteCount() constReturns the total number of bytes written since this object was created. |
explicit StringOutputStream::StringOutputStream(
std::string * target)
std::string * target)
Create a StringOutputStream which appends bytes to the given string.
The string remains property of the caller, but it is mutated in arbitrary ways and MUST NOT be accessed in any way until you're done with the stream. Either be sure there's no further usage, or (safest) destroy the stream before using the contents.
Hint: If you call target->reserve(n) before creating the stream, the first call to Next() will return at least n bytes of buffer space.
virtual bool StringOutputStream::Next(
void ** data,
int * size)
void ** data,
int * size)
Obtains a buffer into which data can be written.
Any data written into this buffer will eventually (maybe instantly, maybe later on) be written to the output.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes in the buffer and "data" points to the buffer.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- Any data which the caller stores in this buffer will eventually be written to the output (unless BackUp() is called).
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void StringOutputStream::BackUp(
int count)
int count)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written.
This is needed when you finish writing all the data you want to write, but the last buffer was bigger than you needed. You don't want to write a bunch of garbage after the end of your data, so you use BackUp() to back up.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
- The caller must not have written anything to the last "count" bytes of that buffer.
Postconditions:
- The last "count" bytes of the last buffer returned by Next() will be ignored.
class CopyingInputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A generic traditional input stream interface.
Lots of traditional input streams (e.g. file descriptors, C stdio streams, and C++ iostreams) expose an interface where every read involves copying bytes into a buffer. If you want to take such an interface and make a ZeroCopyInputStream based on it, simply implement CopyingInputStream and then use CopyingInputStreamAdaptor.
CopyingInputStream implementations should avoid buffering if possible. CopyingInputStreamAdaptor does its own buffering and will read data in large blocks.
Members | |
|---|---|
virtual | ~CopyingInputStream() |
virtual int | Read(void * buffer, int size) = 0Reads up to "size" bytes into the given buffer. more... |
virtual int | Skip(int count)Skips the next "count" bytes of input. more... |
virtual int CopyingInputStream::Read(
void * buffer,
int size) = 0
void * buffer,
int size) = 0
Reads up to "size" bytes into the given buffer.
Returns the number of bytes read. Read() waits until at least one byte is available, or returns zero if no bytes will ever become available (EOF), or -1 if a permanent read error occurred.
virtual int CopyingInputStream::Skip(
int count)
int count)
Skips the next "count" bytes of input.
Returns the number of bytes actually skipped. This will always be exactly equal to "count" unless EOF was reached or a permanent read error occurred.
The default implementation just repeatedly calls Read() into a scratch buffer.
class CopyingInputStreamAdaptor: public ZeroCopyInputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyInputStream which reads from a CopyingInputStream.
This is useful for implementing ZeroCopyInputStreams that read from traditional streams. Note that this class is not really zero-copy.
If you want to read from file descriptors or C++ istreams, this is already implemented for you: use FileInputStream or IstreamInputStream respectively.
Members | |
|---|---|
explicit | CopyingInputStreamAdaptor(CopyingInputStream * copying_stream, int block_size = -1)Creates a stream that reads from the given CopyingInputStream. more... |
| ~CopyingInputStreamAdaptor() |
void | SetOwnsCopyingStream(bool value)Call SetOwnsCopyingStream(true) to tell the CopyingInputStreamAdaptor to delete the underlying CopyingInputStream when it is destroyed. |
implements ZeroCopyInputStream | |
virtual bool | Next(const void ** data, int * size)Obtains a chunk of data from the stream. more... |
virtual void | BackUp(int count) |
virtual bool | Skip(int count)Skips a number of bytes. more... |
virtual int64_t | ByteCount() constReturns the total number of bytes read since this object was created. |
explicit CopyingInputStreamAdaptor::CopyingInputStreamAdaptor(
CopyingInputStream * copying_stream,
int block_size = -1)
CopyingInputStream * copying_stream,
int block_size = -1)
Creates a stream that reads from the given CopyingInputStream.
If a block_size is given, it specifies the number of bytes that should be read and returned with each call to Next(). Otherwise, a reasonable default is used. The caller retains ownership of copying_stream unless SetOwnsCopyingStream(true) is called.
virtual bool CopyingInputStreamAdaptor::Next(
const void ** data,
int * size)
const void ** data,
int * size)
Obtains a chunk of data from the stream.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, there is no more data to return or an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes read and "data" points to a pointer to a buffer containing these bytes.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void CopyingInputStreamAdaptor::BackUp(
int count)
int count)
Backs up a number of bytes, so that the next call to Next() returns data again that was already returned by the last call to Next().
This is useful when writing procedures that are only supposed to read up to a certain point in the input, then return. If Next() returns a buffer that goes beyond what you wanted to read, you can use BackUp() to return to the point where you intended to finish.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
Postconditions:
virtual bool CopyingInputStreamAdaptor::Skip(
int count)
int count)
Skips a number of bytes.
Returns false if the end of the stream is reached or some input error occurred. In the end-of-stream case, the stream is advanced to the end of the stream (so ByteCount() will return the total size of the stream).
class CopyingOutputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A generic traditional output stream interface.
Lots of traditional output streams (e.g. file descriptors, C stdio streams, and C++ iostreams) expose an interface where every write involves copying bytes from a buffer. If you want to take such an interface and make a ZeroCopyOutputStream based on it, simply implement CopyingOutputStream and then use CopyingOutputStreamAdaptor.
CopyingOutputStream implementations should avoid buffering if possible. CopyingOutputStreamAdaptor does its own buffering and will write data in large blocks.
Members | |
|---|---|
virtual | ~CopyingOutputStream() |
virtual bool | Write(const void * buffer, int size) = 0Writes "size" bytes from the given buffer to the output. more... |
virtual bool CopyingOutputStream::Write(
const void * buffer,
int size) = 0
const void * buffer,
int size) = 0
Writes "size" bytes from the given buffer to the output.
Returns true if successful, false on a write error.
class CopyingOutputStreamAdaptor: public ZeroCopyOutputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyOutputStream which writes to a CopyingOutputStream.
This is useful for implementing ZeroCopyOutputStreams that write to traditional streams. Note that this class is not really zero-copy.
If you want to write to file descriptors or C++ ostreams, this is already implemented for you: use FileOutputStream or OstreamOutputStream respectively.
Known subclasses:
Members | |
|---|---|
explicit | CopyingOutputStreamAdaptor(CopyingOutputStream * copying_stream, int block_size = -1)Creates a stream that writes to the given Unix file descriptor. more... |
| ~CopyingOutputStreamAdaptor() |
bool | Flush()Writes all pending data to the underlying stream. more... |
void | SetOwnsCopyingStream(bool value)Call SetOwnsCopyingStream(true) to tell the CopyingOutputStreamAdaptor to delete the underlying CopyingOutputStream when it is destroyed. |
implements ZeroCopyOutputStream | |
virtual bool | Next(void ** data, int * size)Obtains a buffer into which data can be written. more... |
virtual void | BackUp(int count) |
virtual int64_t | ByteCount() constReturns the total number of bytes written since this object was created. |
virtual bool | WriteAliasedRaw(const void * data, int size)Write a given chunk of data to the output. more... |
virtual bool | AllowsAliasing() const |
explicit CopyingOutputStreamAdaptor::CopyingOutputStreamAdaptor(
CopyingOutputStream * copying_stream,
int block_size = -1)
CopyingOutputStream * copying_stream,
int block_size = -1)
Creates a stream that writes to the given Unix file descriptor.
If a block_size is given, it specifies the size of the buffers that should be returned by Next(). Otherwise, a reasonable default is used.
bool CopyingOutputStreamAdaptor::Flush()
Writes all pending data to the underlying stream.
Returns false if a write error occurred on the underlying stream. (The underlying stream itself is not necessarily flushed.)
virtual bool CopyingOutputStreamAdaptor::Next(
void ** data,
int * size)
void ** data,
int * size)
Obtains a buffer into which data can be written.
Any data written into this buffer will eventually (maybe instantly, maybe later on) be written to the output.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes in the buffer and "data" points to the buffer.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- Any data which the caller stores in this buffer will eventually be written to the output (unless BackUp() is called).
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void CopyingOutputStreamAdaptor::BackUp(
int count)
int count)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written.
This is needed when you finish writing all the data you want to write, but the last buffer was bigger than you needed. You don't want to write a bunch of garbage after the end of your data, so you use BackUp() to back up.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
- The caller must not have written anything to the last "count" bytes of that buffer.
Postconditions:
- The last "count" bytes of the last buffer returned by Next() will be ignored.
virtual bool CopyingOutputStreamAdaptor::WriteAliasedRaw(
const void * data,
int size)
const void * data,
int size)
Write a given chunk of data to the output.
Some output streams may implement this in a way that avoids copying. Check AllowsAliasing() before calling WriteAliasedRaw(). It will GOOGLE_CHECK fail if WriteAliasedRaw() is called on a stream that does not allow aliasing.
NOTE: It is caller's responsibility to ensure that the chunk of memory remains live until all of the data has been consumed from the stream.
class LimitingInputStream: public ZeroCopyInputStream
#include <google/protobuf/io/zero_copy_stream_impl_lite.h>
namespace google::protobuf::io
A ZeroCopyInputStream which wraps some other stream and limits it to a particular byte count.
Members | |
|---|---|
| LimitingInputStream(ZeroCopyInputStream * input, int64 limit) |
| ~LimitingInputStream() |
implements ZeroCopyInputStream | |
virtual bool | Next(const void ** data, int * size)Obtains a chunk of data from the stream. more... |
virtual void | BackUp(int count) |
virtual bool | Skip(int count)Skips a number of bytes. more... |
virtual int64_t | ByteCount() constReturns the total number of bytes read since this object was created. |
virtual bool LimitingInputStream::Next(
const void ** data,
int * size)
const void ** data,
int * size)
Obtains a chunk of data from the stream.
Preconditions:
- "size" and "data" are not NULL.
Postconditions:
- If the returned value is false, there is no more data to return or an error occurred. All errors are permanent.
- Otherwise, "size" points to the actual number of bytes read and "data" points to a pointer to a buffer containing these bytes.
- Ownership of this buffer remains with the stream, and the buffer remains valid only until some other method of the stream is called or the stream is destroyed.
- It is legal for the returned buffer to have zero size, as long as repeatedly calling Next() eventually yields a buffer with non-zero size.
virtual void LimitingInputStream::BackUp(
int count)
int count)
Backs up a number of bytes, so that the next call to Next() returns data again that was already returned by the last call to Next().
This is useful when writing procedures that are only supposed to read up to a certain point in the input, then return. If Next() returns a buffer that goes beyond what you wanted to read, you can use BackUp() to return to the point where you intended to finish.
Preconditions:
- The last method called must have been Next().
- count must be less than or equal to the size of the last buffer returned by Next().
Postconditions:
virtual bool LimitingInputStream::Skip(
int count)
int count)
Skips a number of bytes.
Returns false if the end of the stream is reached or some input error occurred. In the end-of-stream case, the stream is advanced to the end of the stream (so ByteCount() will return the total size of the stream).