zero_copy_stream_impl.h

zero_copy_stream_impl.h

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

This file contains common implementations of the interfaces defined in zero_copy_stream.h which are only included in the full (non-lite) protobuf library.

These implementations include Unix file descriptors and C++ iostreams. See also: zero_copy_stream_impl_lite.h

Classes in this file
FileInputStream A  ZeroCopyInputStream which reads from a file descriptor.
FileOutputStream A  ZeroCopyOutputStream which writes to a file descriptor.
IstreamInputStream A  ZeroCopyInputStream which reads from a C++ istream.
OstreamOutputStream A  ZeroCopyOutputStream which writes to a C++ ostream.
ConcatenatingInputStream A  ZeroCopyInputStream which reads from several other streams in sequence.
LimitingInputStream A  ZeroCopyInputStream which wraps some other stream and limits it to a particular byte count.

class FileInputStream: public ZeroCopyInputStream

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

A ZeroCopyInputStream which reads from a file descriptor.

FileInputStream is preferred over using an ifstream with IstreamInputStream. The latter will introduce an extra layer of buffering, harming performance. Also, it's conceivable that FileInputStream could someday be enhanced to use zero-copy file descriptors on OSs which support them.

Members
explicit	FileInputStream(int file_descriptor, int block_size = -1) Creates a stream that reads from the given Unix file descriptor.  more...
	~FileInputStream()
bool	Close() Flushes any buffers and closes the underlying file.  more...
void	SetCloseOnDelete(bool value) By default, the file descriptor is not closed when the stream is destroyed.  more...
int	GetErrno() If an I/O error has occurred on this file descriptor, this is the errno from that error.  more...
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 FileInputStream::FileInputStream(
        int file_descriptor,
        int block_size = -1)

Creates a stream that reads from the given Unix file descriptor.

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.

---

bool FileInputStream::Close()

Flushes any buffers and closes the underlying file.

Returns false if an error occurs during the process; use GetErrno() to examine the error. Even if an error occurs, the file descriptor is closed when this returns.

---

void FileInputStream::SetCloseOnDelete(
        bool value)

By default, the file descriptor is not closed when the stream is destroyed.

Call SetCloseOnDelete(true) to change that. WARNING: This leaves no way for the caller to detect if close() fails. If detecting close() errors is important to you, you should arrange to close the descriptor yourself.

---

int FileInputStream::GetErrno()

If an I/O error has occurred on this file descriptor, this is the errno from that error.

Otherwise, this is zero. Once an error occurs, the stream is broken and all subsequent operations will fail.

---

virtual bool FileInputStream::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 FileInputStream::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 FileInputStream::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 FileOutputStream: public ZeroCopyOutputStream

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

A ZeroCopyOutputStream which writes to a file descriptor.

FileOutputStream is preferred over using an ofstream with OstreamOutputStream. The latter will introduce an extra layer of buffering, harming performance. Also, it's conceivable that FileOutputStream could someday be enhanced to use zero-copy file descriptors on OSs which support them.

Members
explicit	FileOutputStream(int file_descriptor, int block_size = -1) Creates a stream that writes to the given Unix file descriptor.  more...
	~FileOutputStream()
bool	Close() Flushes any buffers and closes the underlying file.  more...
bool	Flush() Flushes  FileOutputStream's buffers but does not close the underlying file.  more...
void	SetCloseOnDelete(bool value) By default, the file descriptor is not closed when the stream is destroyed.  more...
int	GetErrno() If an I/O error has occurred on this file descriptor, this is the errno from that error.  more...
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 FileOutputStream::FileOutputStream(
        int file_descriptor,
        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 FileOutputStream::Close()

Flushes any buffers and closes the underlying file.

Returns false if an error occurs during the process; use GetErrno() to examine the error. Even if an error occurs, the file descriptor is closed when this returns.

---

bool FileOutputStream::Flush()

Flushes FileOutputStream's buffers but does not close the underlying file.

No special measures are taken to ensure that underlying operating system file object is synchronized to disk.

---

void FileOutputStream::SetCloseOnDelete(
        bool value)

By default, the file descriptor is not closed when the stream is destroyed.

Call SetCloseOnDelete(true) to change that. WARNING: This leaves no way for the caller to detect if close() fails. If detecting close() errors is important to you, you should arrange to close the descriptor yourself.

---

int FileOutputStream::GetErrno()

If an I/O error has occurred on this file descriptor, this is the errno from that error.

Otherwise, this is zero. Once an error occurs, the stream is broken and all subsequent operations will fail.

---

virtual bool FileOutputStream::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 FileOutputStream::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 IstreamInputStream: public ZeroCopyInputStream

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

A ZeroCopyInputStream which reads from a C++ istream.

Note that for reading files (or anything represented by a file descriptor), FileInputStream is more efficient.

Members
explicit	IstreamInputStream(istream * stream, int block_size = -1) Creates a stream that reads from the given C++ istream.  more...
	~IstreamInputStream()
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 IstreamInputStream::IstreamInputStream(
        istream * stream,
        int block_size = -1)

Creates a stream that reads from the given C++ istream.

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.

---

virtual bool IstreamInputStream::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 IstreamInputStream::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 IstreamInputStream::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 OstreamOutputStream: public ZeroCopyOutputStream

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

A ZeroCopyOutputStream which writes to a C++ ostream.

Note that for writing files (or anything represented by a file descriptor), FileOutputStream is more efficient.

Members
explicit	OstreamOutputStream(ostream * stream, int block_size = -1) Creates a stream that writes to the given C++ ostream.  more...
	~OstreamOutputStream()
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 OstreamOutputStream::OstreamOutputStream(
        ostream * stream,
        int block_size = -1)

Creates a stream that writes to the given C++ ostream.

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.

---

virtual bool OstreamOutputStream::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 OstreamOutputStream::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 ConcatenatingInputStream: public ZeroCopyInputStream

#include <google/protobuf/io/zero_copy_stream_impl.h>
namespace google::protobuf::io

A ZeroCopyInputStream which reads from several other streams in sequence.

ConcatenatingInputStream is unable to distinguish between end-of-stream and read errors in the underlying streams, so it assumes any errors mean end-of-stream. So, if the underlying streams fail for any other reason, ConcatenatingInputStream may do odd things. It is suggested that you do not use ConcatenatingInputStream on streams that might produce read errors other than end-of-stream.

Members
	ConcatenatingInputStream(ZeroCopyInputStream *const streams, int count) All streams passed in as well as the array itself must remain valid until the  ConcatenatingInputStream is destroyed.
	~ConcatenatingInputStream()
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.

---

virtual bool ConcatenatingInputStream::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 ConcatenatingInputStream::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 ConcatenatingInputStream::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 LimitingInputStream: public ZeroCopyInputStream

#include <google/protobuf/io/zero_copy_stream_impl.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) 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.

---

virtual bool LimitingInputStream::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 LimitingInputStream::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 LimitingInputStream::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).