5 // Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
7 // Distributed under the Boost Software License, Version 1.0. (See accompanying
8 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
11 #ifndef BOOST_ASIO_BASIC_STREAMBUF_HPP
12 #define BOOST_ASIO_BASIC_STREAMBUF_HPP
14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
18 #include <boost/asio/detail/config.hpp>
20 #if !defined(BOOST_ASIO_NO_IOSTREAM)
27 #include <boost/asio/basic_streambuf_fwd.hpp>
28 #include <boost/asio/buffer.hpp>
29 #include <boost/asio/detail/limits.hpp>
30 #include <boost/asio/detail/noncopyable.hpp>
31 #include <boost/asio/detail/throw_exception.hpp>
33 #include <boost/asio/detail/push_options.hpp>
38 /// Automatically resizable buffer class based on std::streambuf.
40 * The @c basic_streambuf class is derived from @c std::streambuf to associate
41 * the streambuf's input and output sequences with one or more character
42 * arrays. These character arrays are internal to the @c basic_streambuf
43 * object, but direct access to the array elements is provided to permit them
44 * to be used efficiently with I/O operations. Characters written to the output
45 * sequence of a @c basic_streambuf object are appended to the input sequence
48 * The @c basic_streambuf class's public interface is intended to permit the
49 * following implementation strategies:
51 * @li A single contiguous character array, which is reallocated as necessary
52 * to accommodate changes in the size of the character sequence. This is the
53 * implementation approach currently used in Asio.
55 * @li A sequence of one or more character arrays, where each array is of the
56 * same size. Additional character array objects are appended to the sequence
57 * to accommodate changes in the size of the character sequence.
59 * @li A sequence of one or more character arrays of varying sizes. Additional
60 * character array objects are appended to the sequence to accommodate changes
61 * in the size of the character sequence.
63 * The constructor for basic_streambuf accepts a @c size_t argument specifying
64 * the maximum of the sum of the sizes of the input sequence and output
65 * sequence. During the lifetime of the @c basic_streambuf object, the following
67 * @code size() <= max_size()@endcode
68 * Any member function that would, if successful, cause the invariant to be
69 * violated shall throw an exception of class @c std::length_error.
71 * The constructor for @c basic_streambuf takes an Allocator argument. A copy
72 * of this argument is used for any memory allocation performed, by the
73 * constructor and by all member functions, during the lifetime of each @c
74 * basic_streambuf object.
77 * Writing directly from an streambuf to a socket:
79 * boost::asio::streambuf b;
80 * std::ostream os(&b);
81 * os << "Hello, World!\n";
83 * // try sending some data in input sequence
84 * size_t n = sock.send(b.data());
86 * b.consume(n); // sent data is removed from input sequence
89 * Reading from a socket directly into a streambuf:
91 * boost::asio::streambuf b;
93 * // reserve 512 bytes in output sequence
94 * boost::asio::streambuf::mutable_buffers_type bufs = b.prepare(512);
96 * size_t n = sock.receive(bufs);
98 * // received data is "committed" from output sequence to input sequence
101 * std::istream is(&b);
106 #if defined(GENERATING_DOCUMENTATION)
107 template <typename Allocator = std::allocator<char> >
109 template <typename Allocator>
111 class basic_streambuf
112 : public std::streambuf,
116 #if defined(GENERATING_DOCUMENTATION)
117 /// The type used to represent the input sequence as a list of buffers.
118 typedef implementation_defined const_buffers_type;
120 /// The type used to represent the output sequence as a list of buffers.
121 typedef implementation_defined mutable_buffers_type;
123 typedef boost::asio::const_buffers_1 const_buffers_type;
124 typedef boost::asio::mutable_buffers_1 mutable_buffers_type;
127 /// Construct a basic_streambuf object.
129 * Constructs a streambuf with the specified maximum size. The initial size
130 * of the streambuf's input sequence is 0.
132 explicit basic_streambuf(
133 std::size_t maximum_size = (std::numeric_limits<std::size_t>::max)(),
134 const Allocator& allocator = Allocator())
135 : max_size_(maximum_size),
138 std::size_t pend = (std::min<std::size_t>)(max_size_, buffer_delta);
139 buffer_.resize((std::max<std::size_t>)(pend, 1));
140 setg(&buffer_[0], &buffer_[0], &buffer_[0]);
141 setp(&buffer_[0], &buffer_[0] + pend);
144 /// Get the size of the input sequence.
146 * @returns The size of the input sequence. The value is equal to that
147 * calculated for @c s in the following code:
150 * const_buffers_type bufs = data();
151 * const_buffers_type::const_iterator i = bufs.begin();
152 * while (i != bufs.end())
154 * const_buffer buf(*i++);
155 * s += buffer_size(buf);
159 std::size_t size() const
161 return pptr() - gptr();
164 /// Get the maximum size of the basic_streambuf.
166 * @returns The allowed maximum of the sum of the sizes of the input sequence
167 * and output sequence.
169 std::size_t max_size() const
174 /// Get a list of buffers that represents the input sequence.
176 * @returns An object of type @c const_buffers_type that satisfies
177 * ConstBufferSequence requirements, representing all character arrays in the
180 * @note The returned object is invalidated by any @c basic_streambuf member
181 * function that modifies the input sequence or output sequence.
183 const_buffers_type data() const
185 return boost::asio::buffer(boost::asio::const_buffer(gptr(),
186 (pptr() - gptr()) * sizeof(char_type)));
189 /// Get a list of buffers that represents the output sequence, with the given
192 * Ensures that the output sequence can accommodate @c n characters,
193 * reallocating character array objects as necessary.
195 * @returns An object of type @c mutable_buffers_type that satisfies
196 * MutableBufferSequence requirements, representing character array objects
197 * at the start of the output sequence such that the sum of the buffer sizes
200 * @throws std::length_error If <tt>size() + n > max_size()</tt>.
202 * @note The returned object is invalidated by any @c basic_streambuf member
203 * function that modifies the input sequence or output sequence.
205 mutable_buffers_type prepare(std::size_t n)
208 return boost::asio::buffer(boost::asio::mutable_buffer(
209 pptr(), n * sizeof(char_type)));
212 /// Move characters from the output sequence to the input sequence.
214 * Appends @c n characters from the start of the output sequence to the input
215 * sequence. The beginning of the output sequence is advanced by @c n
218 * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
219 * no intervening operations that modify the input or output sequence.
221 * @note If @c n is greater than the size of the output sequence, the entire
222 * output sequence is moved to the input sequence and no error is issued.
224 void commit(std::size_t n)
226 if (pptr() + n > epptr())
227 n = epptr() - pptr();
228 pbump(static_cast<int>(n));
229 setg(eback(), gptr(), pptr());
232 /// Remove characters from the input sequence.
234 * Removes @c n characters from the beginning of the input sequence.
236 * @note If @c n is greater than the size of the input sequence, the entire
237 * input sequence is consumed and no error is issued.
239 void consume(std::size_t n)
241 if (egptr() < pptr())
242 setg(&buffer_[0], gptr(), pptr());
243 if (gptr() + n > pptr())
245 gbump(static_cast<int>(n));
249 enum { buffer_delta = 128 };
251 /// Override std::streambuf behaviour.
253 * Behaves according to the specification of @c std::streambuf::underflow().
259 setg(&buffer_[0], gptr(), pptr());
260 return traits_type::to_int_type(*gptr());
264 return traits_type::eof();
268 /// Override std::streambuf behaviour.
270 * Behaves according to the specification of @c std::streambuf::overflow(),
271 * with the specialisation that @c std::length_error is thrown if appending
272 * the character to the input sequence would require the condition
273 * <tt>size() > max_size()</tt> to be true.
275 int_type overflow(int_type c)
277 if (!traits_type::eq_int_type(c, traits_type::eof()))
279 if (pptr() == epptr())
281 std::size_t buffer_size = pptr() - gptr();
282 if (buffer_size < max_size_ && max_size_ - buffer_size < buffer_delta)
284 reserve(max_size_ - buffer_size);
288 reserve(buffer_delta);
292 *pptr() = traits_type::to_char_type(c);
297 return traits_type::not_eof(c);
300 void reserve(std::size_t n)
302 // Get current stream positions as offsets.
303 std::size_t gnext = gptr() - &buffer_[0];
304 std::size_t pnext = pptr() - &buffer_[0];
305 std::size_t pend = epptr() - &buffer_[0];
307 // Check if there is already enough space in the put area.
308 if (n <= pend - pnext)
313 // Shift existing contents of get area to start of buffer.
317 std::memmove(&buffer_[0], &buffer_[0] + gnext, pnext);
320 // Ensure buffer is large enough to hold at least the specified size.
321 if (n > pend - pnext)
323 if (n <= max_size_ && pnext <= max_size_ - n)
326 buffer_.resize((std::max<std::size_t>)(pend, 1));
330 std::length_error ex("boost::asio::streambuf too long");
331 boost::asio::detail::throw_exception(ex);
335 // Update stream positions.
336 setg(&buffer_[0], &buffer_[0], &buffer_[0] + pnext);
337 setp(&buffer_[0] + pnext, &buffer_[0] + pend);
341 std::size_t max_size_;
342 std::vector<char_type, Allocator> buffer_;
344 // Helper function to get the preferred size for reading data.
345 friend std::size_t read_size_helper(
346 basic_streambuf& sb, std::size_t max_size)
348 return std::min<std::size_t>(
349 std::max<std::size_t>(512, sb.buffer_.capacity() - sb.size()),
350 std::min<std::size_t>(max_size, sb.max_size() - sb.size()));
354 // Helper function to get the preferred size for reading data. Used for any
355 // user-provided specialisations of basic_streambuf.
356 template <typename Allocator>
357 inline std::size_t read_size_helper(
358 basic_streambuf<Allocator>& sb, std::size_t max_size)
360 return std::min<std::size_t>(512,
361 std::min<std::size_t>(max_size, sb.max_size() - sb.size()));
367 #include <boost/asio/detail/pop_options.hpp>
369 #endif // !defined(BOOST_ASIO_NO_IOSTREAM)
371 #endif // BOOST_ASIO_BASIC_STREAMBUF_HPP