Search Toolkit Book for CRStream
Note about the "buf_size" parameter for streams in this API. More...
#include <corelib/rwstream.hpp>
Inheritance diagram for CRStream:
Collaboration diagram for CRStream:
Public Member Functions | |
| CRStream (IReader *r, streamsize buf_size=0, CT_CHAR_TYPE *buf=0, CRWStreambuf::TFlags stm_flags=0) | |
Private Attributes | |
| CRWStreambuf | m_Sb |
Detailed Description
Note about the "buf_size" parameter for streams in this API.
CRWStream implementation is targeted at minimizing in-memory data copy operations associated with I/O for intermediate buffering. For that, the following policies apply:
1. No read operation from the input device shall request less than the internal stream buffer size. In cases when the user code requests more than the internal stream buffer size, the request may be passed through to the input device to read directly into the buffer provided by user. In that case, the read request can only be larger than the the size of the internal stream buffer.
2. Write operations to the output device are done in full buffers, unless: a. An incoming user write request is larger than the internal buffer, then the contents of the internal buffer gets flushed first (which may comprise of fewer bytes than the size of the internal buffer) followed by a direct write request of the user's block (larger than the internal stream buffer); b. Flushing of the internal buffer (including 2a above) resulted in a short write to the device (fewer bytes actually written). Then, the successive write attempt may contain fewer bytes than the size of the internal stream buffer (namely, the remainder of what has been left behind by the preceding [short] write). This case also applies when the flushing is done internally in a tied stream prior to reading.
However, any portable implementation should *not* rely on how data chunks are being flushed or requested by the stream implementations. If further factoring into blocks (e.g. specially-sized) is necessary for the I/O device to operate correctly, that should be implemented at the level of the respective IReader/IWriter API explicitly. Reader-based input stream.
- See also
- IReader
- Attention
- The underlying IReader is expected to block in Read() if unable to extract at least one byte from the input device. If unable to read anything, it must never return eRW_Success. In order for applications to be able to use istream::readsome() (or CStreamUtils::Readsome()) on CRstream, the underlying IReader must fully implement the PendingCount() method.
- Warning
- The eRW_Error return code from any method of the underlying IReader may get converted to an exception thrown if the requested I/O operation cannot advance any data in stream. That would make the stream to catch it, and to set ios_base::badbit (ios_base::bad() returns true), then perhaps to re-throw the exception (if so allowed by the stream). Note that accessing streambuf's methods directly won't shield from throwing the exception, so it will always be delivered to user's code.
- Parameters
-
buf_size specifies the number of bytes for internal I/O buffer, entirely used for reading by the underlying stream buffer object CRWStreambuf; 0 causes to create a buffer of some default size. buf may specify the buffer location (if 0, an internal storage gets allocated and later freed upon stream destruction). stm_flags controls whether IReader is destroyed upon stream destruction, whether exceptions get logged (or leaked, or caught silently), etc.
Special case of "buf_size" == 1 creates an unbuffered stream ("buf", if provided, is still used internally as a one-char un-get location).
- See also
- CRWStreambuf::TFlags, IWStream, IRWStream, CStreamUtils
Definition at line 121 of file rwstream.hpp.
The documentation for this class was generated from the following file:
- include/corelib/rwstream.hpp
