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 | |
|---|---|
A ZeroCopyInputStream which reads from a file descriptor. | |
A ZeroCopyOutputStream which writes to a file descriptor. | |
A ZeroCopyInputStream which reads from a C++ istream. | |
A ZeroCopyOutputStream which writes to a C++ ostream. | |
A ZeroCopyInputStream which reads from several other streams in sequence. | |
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... |
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() constIf 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) |
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 FileInputStream::FileInputStream(
int file_descriptor,
int block_size = -1)
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)
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() const
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)
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)
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 FileInputStream::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 FileOutputStream: public CopyingOutputStreamAdaptor
#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... |
void | SetCloseOnDelete(bool value)By default, the file descriptor is not closed when the stream is destroyed. more... |
int | GetErrno() constIf an I/O error has occurred on this file descriptor, this is the errno from that error. more... |
explicit FileOutputStream::FileOutputStream(
int file_descriptor,
int block_size = -1)
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.
void FileOutputStream::SetCloseOnDelete(
bool value)
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() const
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.
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(std::istream * stream, int block_size = -1)Creates a stream that reads from the given C++ istream. 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) |
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 IstreamInputStream::IstreamInputStream(
std::istream * stream,
int block_size = -1)
std::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)
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)
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 IstreamInputStream::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 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(std::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) |
virtual int64_t | ByteCount() constReturns the total number of bytes written since this object was created. |
explicit OstreamOutputStream::OstreamOutputStream(
std::ostream * stream,
int block_size = -1)
std::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)
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)
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) |
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 ConcatenatingInputStream::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 ConcatenatingInputStream::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 ConcatenatingInputStream::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).