NCBI C++ ToolKit
rwstream.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CORELIB___RWSTREAM__HPP
2 #define CORELIB___RWSTREAM__HPP
3 
4 /* $Id: rwstream.hpp 97234 2022-06-28 18:07:53Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Authors: Anton Lavrentiev
30  *
31  * File Description:
32  * Reader-writer based streams
33  *
34  */
35 
36 /// @file rwstream.hpp
37 /// Reader-writer based streams
38 /// @sa IReader, IWriter, IReaderWriter, CRWStreambuf
39 
40 #include <corelib/ncbimisc.hpp>
42 
43 /** @addtogroup Stream
44  *
45  * @{
46  */
47 
48 
50 
51 
52 /// Note about the "buf_size" parameter for streams in this API.
53 ///
54 /// CRWStream implementation is targeted at minimizing in-memory data copy
55 /// operations associated with I/O for intermediate buffering. For that, the
56 /// following policies apply:
57 ///
58 /// 1. No read operation from the input device shall request less than the
59 /// internal stream buffer size. In cases when the user code requests more
60 /// than the internal stream buffer size, the request may be passed through
61 /// to the input device to read directly into the buffer provided by user.
62 /// In that case, the read request can only be larger than the the size of
63 /// the internal stream buffer.
64 ///
65 /// 2. Write operations to the output device are done in full buffers, unless:
66 /// a. An incoming user write request is larger than the internal buffer,
67 /// then the contents of the internal buffer gets flushed first (which may
68 /// comprise of fewer bytes than the size of the internal buffer) followed
69 /// by a direct write request of the user's block (larger than the internal
70 /// stream buffer);
71 /// b. Flushing of the internal buffer (including 2a above) resulted in a
72 /// short write to the device (fewer bytes actually written). Then, the
73 /// successive write attempt may contain fewer bytes than the size of the
74 /// internal stream buffer (namely, the remainder of what has been left
75 /// behind by the preceding [short] write). This case also applies when
76 /// the flushing is done internally in a tied stream prior to reading.
77 ///
78 /// However, any portable implementation should *not* rely on how data chunks
79 /// are being flushed or requested by the stream implementations. If further
80 /// factoring into blocks (e.g. specially-sized) is necessary for the I/O
81 /// device to operate correctly, that should be implemented at the level of
82 /// the respective IReader/IWriter API explicitly.
83 
84 
85 /// Reader-based input stream.
86 /// @sa IReader
87 /// @attention
88 /// The underlying IReader is expected to block in Read() if unable to
89 /// extract at least one byte from the input device. If unable to read
90 /// anything, it must never return eRW_Success. In order for applications
91 /// to be able to use istream::readsome() (or CStreamUtils::Readsome()) on
92 /// CRstream, the underlying IReader must fully implement the
93 /// PendingCount() method.
94 /// @warning
95 /// The eRW_Error return code from any method of the underlying IReader may
96 /// get converted to an exception thrown if the requested I/O operation
97 /// cannot advance any data in stream. That would make the stream to catch
98 /// it, and to set ios_base::badbit (ios_base::bad() returns true), then
99 /// perhaps to re-throw the exception (if so allowed by the stream). Note
100 /// that accessing streambuf's methods directly won't shield from throwing
101 /// the exception, so it will always be delivered to user's code.
102 ///
103 /// @param buf_size
104 /// specifies the number of bytes for internal I/O buffer, entirely used
105 /// for reading by the underlying stream buffer object CRWStreambuf;
106 /// 0 causes to create a buffer of some default size.
107 ///
108 /// @param buf
109 /// may specify the buffer location (if 0, an internal storage gets
110 /// allocated and later freed upon stream destruction).
111 ///
112 /// @param stm_flags
113 /// controls whether IReader is destroyed upon stream destruction,
114 /// whether exceptions get logged (or leaked, or caught silently), etc.
115 ///
116 /// Special case of "buf_size" == 1 creates an unbuffered stream ("buf", if
117 /// provided, is still used internally as a one-char un-get location).
118 ///
119 /// @sa CRWStreambuf::TFlags, IWStream, IRWStream, CStreamUtils
120 
122 {
123 public:
125  streamsize buf_size = 0,
126  CT_CHAR_TYPE* buf = 0,
127  CRWStreambuf::TFlags stm_flags = 0)
128  : CNcbiIstream(r ? &m_Sb : 0),
129  m_Sb(r, 0, buf_size, buf, stm_flags)
130  { }
131 
132 private:
134 };
135 
136 
137 /// Writer-based output stream.
138 /// @sa IWriter
139 /// @attention
140 /// Underlying IWriter is expected to block in Write() if unable to output
141 /// at least one byte to the output device. If unable to output anything,
142 /// it must never return eRW_Success.
143 /// @warning
144 /// The eRW_Error return code from any method of the underlying IWriter may
145 /// get converted to an exception thrown if the requested I/O operation
146 /// cannot advance any data in stream. That would make the stream to catch
147 /// it, and to set ios_base::badbit (ios_base::bad() returns true), then
148 /// perhaps to re-throw the exception (if so allowed by the stream). Note
149 /// that accessing streambuf's methods directly won't shield from throwing
150 /// the exception, so it will always be delivered to user's code.
151 ///
152 /// @param buf_size
153 /// specifies the number of bytes for internal I/O buffer, entirely used
154 /// for writing by the underlying stream buffer object CRWStreambuf;
155 /// 0 causes to create a buffer of some default size.
156 ///
157 /// @param buf
158 /// may specify the buffer location (if 0, an internal storage gets
159 /// allocated and later freed upon stream destruction).
160 ///
161 /// @param stm_flags
162 /// controls whether IWriter is destroyed upon stream destruction,
163 /// whether exceptions get logged (or leaked, or caught silently), etc.
164 ///
165 /// Special case of "buf_size" == 1 creates an unbuffered stream ("buf", if
166 /// provided, is ignored).
167 ///
168 /// @sa CRWStreambuf::TFlags, IRStream, IRWStream
169 
171 {
172 public:
174  streamsize buf_size = 0,
175  CT_CHAR_TYPE* buf = 0,
176  CRWStreambuf::TFlags stm_flags = 0)
177  : CNcbiOstream(w ? &m_Sb : 0),
178  m_Sb(0, w, buf_size, buf, stm_flags)
179  { }
180 
181 private:
183 };
184 
185 
186 /// Reader-writer based input-output stream.
187 /// @sa IReaderWriter, IReader, IWriter
188 ///
189 /// @param buf_size
190 /// specifies the number of bytes for internal I/O buffer, half of which is
191 /// to be used for reading and the other half -- for writing, by the
192 /// underlying stream buffer object CRWStreambuf;
193 /// 0 causes to create a buffer of some default size.
194 ///
195 /// @param buf
196 /// may specify the buffer location (if 0, an internal storage gets
197 /// allocated and later freed upon stream destruction).
198 ///
199 /// @param stm_flags
200 /// controls whether IReaderWriter is destroyed upon stream destruction,
201 /// whether exceptions get logged (or leaked, or caught silently), etc.
202 ///
203 /// Special case of "buf_size" == 1 creates an unbuffered stream ("buf", if
204 /// provided, may still be used internally as a one-char un-get location).
205 ///
206 /// @sa CRWStreambuf::TFlags, IRStream, IWStream
207 
209 {
210 public:
212  streamsize buf_size = 0,
213  CT_CHAR_TYPE* buf = 0,
214  CRWStreambuf::TFlags stm_flags = 0)
215  : CNcbiIostream(rw ? &m_Sb : 0),
216  m_Sb(rw, buf_size, buf, stm_flags)
217  { }
218 
220  IWriter* w,
221  streamsize buf_size = 0,
222  CT_CHAR_TYPE* buf = 0,
223  CRWStreambuf::TFlags stm_flags = 0)
224  : CNcbiIostream(r || w ? &m_Sb : 0),
225  m_Sb(r, w, buf_size, buf, stm_flags)
226  { }
227 
228 private:
230 };
231 
232 
234 
235 
236 /* @} */
237 
238 #endif /* CORELIB___RWSTREAM__HPP */
Note about the "buf_size" parameter for streams in this API.
Definition: rwstream.hpp:122
Reader-writer based input-output stream.
Definition: rwstream.hpp:209
Reader-writer-based stream buffer.
Definition: rwstreambuf.hpp:60
int TFlags
Bitwise OR of EFlags.
Definition: rwstreambuf.hpp:74
Writer-based output stream.
Definition: rwstream.hpp:171
A very basic data-read/write interface.
A very basic data-read interface.
A very basic data-write interface.
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
CRWStream(IReader *r, IWriter *w, streamsize buf_size=0, CT_CHAR_TYPE *buf=0, CRWStreambuf::TFlags stm_flags=0)
Definition: rwstream.hpp:219
CWStream(IWriter *w, streamsize buf_size=0, CT_CHAR_TYPE *buf=0, CRWStreambuf::TFlags stm_flags=0)
Definition: rwstream.hpp:173
CRStream(IReader *r, streamsize buf_size=0, CT_CHAR_TYPE *buf=0, CRWStreambuf::TFlags stm_flags=0)
Definition: rwstream.hpp:124
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
IO_PREFIX::iostream CNcbiIostream
Portable alias for iostream.
Definition: ncbistre.hpp:152
CRWStreambuf m_Sb
Definition: rwstream.hpp:133
CRWStreambuf m_Sb
Definition: rwstream.hpp:229
CRWStreambuf m_Sb
Definition: rwstream.hpp:182
CRWStream(IReaderWriter *rw, streamsize buf_size=0, CT_CHAR_TYPE *buf=0, CRWStreambuf::TFlags stm_flags=0)
Definition: rwstream.hpp:211
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
#define CT_CHAR_TYPE
Definition: ncbistre.hpp:729
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
char * buf
Miscellaneous common-use basic types and functionality.
double r(size_t dimension_, const Int4 *score_, const double *prob_, double theta_)
Reader-writer-based stream buffer.
Modified on Tue Jun 18 13:39:18 2024 by modify_doxy.py rev. 669887