My favorites | English | Sign in

Protocol Buffers

zero_copy_stream_impl_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 generic traditional output stream interface.

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)
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(). more...
virtual bool
Skip(int count)
Skips a number of bytes. more...
virtual int64
ByteCount() const
Returns the total number of bytes read since this object was created.

ArrayInputStream::ArrayInputStream(
        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)

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)

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:

  • The last "count" bytes of the last buffer returned by Next() will be pushed back into the stream. Subsequent calls to Next() will return the same data again before producing new data.

virtual bool ArrayInputStream::Skip(
        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)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written. more...
virtual int64
ByteCount() const
Returns the total number of bytes written since this object was created.

ArrayOutputStream::ArrayOutputStream(
        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)

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)

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(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)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written. more...
virtual int64
ByteCount() const
Returns the total number of bytes written since this object was created.

explicit StringOutputStream::StringOutputStream(
        string * target)

Create a StringOutputStream which appends bytes to the given string.

The string remains property of the caller, but it MUST NOT be accessed in any way until the stream is destroyed.

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)

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)

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) = 0
Reads 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

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)

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)
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(). more...
virtual bool
Skip(int count)
Skips a number of bytes. more...
virtual int64
ByteCount() const
Returns the total number of bytes read since this object was created.

explicit CopyingInputStreamAdaptor::CopyingInputStreamAdaptor(
        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)

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)

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:

  • The last "count" bytes of the last buffer returned by Next() will be pushed back into the stream. Subsequent calls to Next() will return the same data again before producing new data.

virtual bool CopyingInputStreamAdaptor::Skip(
        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) = 0
Writes "size" bytes from the given buffer to the output. more...

virtual bool CopyingOutputStream::Write(
        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.

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)
Backs up a number of bytes, so that the end of the last buffer returned by Next() is not actually written. more...
virtual int64
ByteCount() const
Returns the total number of bytes written since this object was created.

explicit CopyingOutputStreamAdaptor::CopyingOutputStreamAdaptor(
        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)

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)

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.