boost/asio/basic_streambuf.hpp

   1 //
   2 // basic_streambuf.hpp
   3 // ~~~~~~~~~~~~~~~~~~~
   4 //
   5 // Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   6 //
   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)
   9 //
  10
  11 #ifndef BOOST_ASIO_BASIC_STREAMBUF_HPP
  12 #define BOOST_ASIO_BASIC_STREAMBUF_HPP
  13
  14 #if defined(_MSC_VER) && (_MSC_VER >= 1200)
  15 # pragma once
  16 #endif // defined(_MSC_VER) && (_MSC_VER >= 1200)
  17
  18 #include <boost/asio/detail/push_options.hpp>
  19
  20 #include <boost/asio/detail/push_options.hpp>
  21 #include <algorithm>
  22 #include <cstring>
  23 #include <limits>
  24 #include <memory>
  25 #include <stdexcept>
  26 #include <streambuf>
  27 #include <vector>
  28 #include <boost/asio/detail/pop_options.hpp>
  29
  30 #include <boost/asio/buffer.hpp>
  31 #include <boost/asio/detail/noncopyable.hpp>
  32
  33 namespace boost {
  34 namespace asio {
  35
  36 /// Automatically resizable buffer class based on std::streambuf.
  37 /**
  38  * The @c basic_streambuf class is derived from @c std::streambuf to associate
  39  * the streambuf's input and output sequences with one or more character
  40  * arrays. These character arrays are internal to the @c basic_streambuf
  41  * object, but direct access to the array elements is provided to permit them
  42  * to be used efficiently with I/O operations. Characters written to the output
  43  * sequence of a @c basic_streambuf object are appended to the input sequence
  44  * of the same object.
  45  *
  46  * The @c basic_streambuf class's public interface is intended to permit the
  47  * following implementation strategies:
  48  *
  49  * @li A single contiguous character array, which is reallocated as necessary
  50  * to accommodate changes in the size of the character sequence. This is the
  51  * implementation approach currently used in Asio.
  52  *
  53  * @li A sequence of one or more character arrays, where each array is of the
  54  * same size. Additional character array objects are appended to the sequence
  55  * to accommodate changes in the size of the character sequence.
  56  *
  57  * @li A sequence of one or more character arrays of varying sizes. Additional
  58  * character array objects are appended to the sequence to accommodate changes
  59  * in the size of the character sequence.
  60  *
  61  * The constructor for basic_streambuf accepts a @c size_t argument specifying
  62  * the maximum of the sum of the sizes of the input sequence and output
  63  * sequence. During the lifetime of the @c basic_streambuf object, the following
  64  * invariant holds:
  65  * @code size() <= max_size()@endcode
  66  * Any member function that would, if successful, cause the invariant to be
  67  * violated shall throw an exception of class @c std::length_error.
  68  *
  69  * The constructor for @c basic_streambuf takes an Allocator argument. A copy
  70  * of this argument is used for any memory allocation performed, by the
  71  * constructor and by all member functions, during the lifetime of each @c
  72  * basic_streambuf object.
  73  *
  74  * @par Examples
  75  * Writing directly from an streambuf to a socket:
  76  * @code
  77  * boost::asio::streambuf b;
  78  * std::ostream os(&b);
  79  * os << "Hello, World!\n";
  80  *
  81  * // try sending some data in input sequence
  82  * size_t n = sock.send(b.data());
  83  *
  84  * b.consume(n); // sent data is removed from input sequence
  85  * @endcode
  86  *
  87  * Reading from a socket directly into a streambuf:
  88  * @code
  89  * boost::asio::streambuf b;
  90  *
  91  * // reserve 512 bytes in output sequence
  92  * boost::asio::streambuf::const_buffers_type bufs = b.prepare(512);
  93  *
  94  * size_t n = sock.receive(bufs);
  95  *
  96  * // received data is "committed" from output sequence to input sequence
  97  * b.commit(n);
  98  *
  99  * std::istream is(&b);
 100  * std::string s;
 101  * is >> s;
 102  * @endcode
 103  */
 104 template <typename Allocator = std::allocator<char> >
 105 class basic_streambuf
 106   : public std::streambuf,
 107     private noncopyable
 108 {
 109 public:
 110 #if defined(GENERATING_DOCUMENTATION)
 111   /// The type used to represent the input sequence as a list of buffers.
 112   typedef implementation_defined const_buffers_type;
 113
 114   /// The type used to represent the output sequence as a list of buffers.
 115   typedef implementation_defined mutable_buffers_type;
 116 #else
 117   typedef boost::asio::const_buffers_1 const_buffers_type;
 118   typedef boost::asio::mutable_buffers_1 mutable_buffers_type;
 119 #endif
 120
 121   /// Construct a basic_streambuf object.
 122   /**
 123    * Constructs a streambuf with the specified maximum size. The initial size
 124    * of the streambuf's input sequence is 0.
 125    */
 126   explicit basic_streambuf(
 127       std::size_t max_size = (std::numeric_limits<std::size_t>::max)(),
 128       const Allocator& allocator = Allocator())
 129     : max_size_(max_size),
 130       buffer_(allocator)
 131   {
 132     std::size_t pend = (std::min<std::size_t>)(max_size_, buffer_delta);
 133     buffer_.resize((std::max<std::size_t>)(pend, 1));
 134     setg(&buffer_[0], &buffer_[0], &buffer_[0]);
 135     setp(&buffer_[0], &buffer_[0] + pend);
 136   }
 137
 138   /// Get the size of the input sequence.
 139   /**
 140    * @returns The size of the input sequence. The value is equal to that
 141    * calculated for @c s in the following code:
 142    * @code
 143    * size_t s = 0;
 144    * const_buffers_type bufs = data();
 145    * const_buffers_type::const_iterator i = bufs.begin();
 146    * while (i != bufs.end())
 147    * {
 148    *   const_buffer buf(*i++);
 149    *   s += buffer_size(buf);
 150    * }
 151    * @endcode
 152    */
 153   std::size_t size() const
 154   {
 155     return pptr() - gptr();
 156   }
 157
 158   /// Get the maximum size of the basic_streambuf.
 159   /**
 160    * @returns The allowed maximum of the sum of the sizes of the input sequence
 161    * and output sequence.
 162    */
 163   std::size_t max_size() const
 164   {
 165     return max_size_;
 166   }
 167
 168   /// Get a list of buffers that represents the input sequence.
 169   /**
 170    * @returns An object of type @c const_buffers_type that satisfies
 171    * ConstBufferSequence requirements, representing all character arrays in the
 172    * input sequence.
 173    *
 174    * @note The returned object is invalidated by any @c basic_streambuf member
 175    * function that modifies the input sequence or output sequence.
 176    */
 177   const_buffers_type data() const
 178   {
 179     return boost::asio::buffer(boost::asio::const_buffer(gptr(),
 180           (pptr() - gptr()) * sizeof(char_type)));
 181   }
 182
 183   /// Get a list of buffers that represents the output sequence, with the given
 184   /// size.
 185   /**
 186    * Ensures that the output sequence can accommodate @c n characters,
 187    * reallocating character array objects as necessary.
 188    *
 189    * @returns An object of type @c mutable_buffers_type that satisfies
 190    * MutableBufferSequence requirements, representing character array objects
 191    * at the start of the output sequence such that the sum of the buffer sizes
 192    * is @c n.
 193    *
 194    * @throws std::length_error If <tt>size() + n > max_size()</tt>.
 195    *
 196    * @note The returned object is invalidated by any @c basic_streambuf member
 197    * function that modifies the input sequence or output sequence.
 198    */
 199   mutable_buffers_type prepare(std::size_t n)
 200   {
 201     reserve(n);
 202     return boost::asio::buffer(boost::asio::mutable_buffer(
 203           pptr(), n * sizeof(char_type)));
 204   }
 205
 206   /// Move characters from the output sequence to the input sequence.
 207   /**
 208    * Appends @c n characters from the start of the output sequence to the input
 209    * sequence. The beginning of the output sequence is advanced by @c n
 210    * characters.
 211    *
 212    * Requires a preceding call <tt>prepare(x)</tt> where <tt>x >= n</tt>, and
 213    * no intervening operations that modify the input or output sequence.
 214    *
 215    * @throws std::length_error If @c n is greater than the size of the output
 216    * sequence.
 217    */
 218   void commit(std::size_t n)
 219   {
 220     if (pptr() + n > epptr())
 221       n = epptr() - pptr();
 222     pbump(static_cast<int>(n));
 223     setg(eback(), gptr(), pptr());
 224   }
 225
 226   /// Remove characters from the input sequence.
 227   /**
 228    * Removes @c n characters from the beginning of the input sequence.
 229    *
 230    * @throws std::length_error If <tt>n > size()</tt>.
 231    */
 232   void consume(std::size_t n)
 233   {
 234     if (gptr() + n > pptr())
 235       n = pptr() - gptr();
 236     gbump(static_cast<int>(n));
 237   }
 238
 239 protected:
 240   enum { buffer_delta = 128 };
 241
 242   /// Override std::streambuf behaviour.
 243   /**
 244    * Behaves according to the specification of @c std::streambuf::underflow().
 245    */
 246   int_type underflow()
 247   {
 248     if (gptr() < pptr())
 249     {
 250       setg(&buffer_[0], gptr(), pptr());
 251       return traits_type::to_int_type(*gptr());
 252     }
 253     else
 254     {
 255       return traits_type::eof();
 256     }
 257   }
 258
 259   /// Override std::streambuf behaviour.
 260   /**
 261    * Behaves according to the specification of @c std::streambuf::overflow(),
 262    * with the specialisation that @c std::length_error is thrown if appending
 263    * the character to the input sequence would require the condition
 264    * <tt>size() > max_size()</tt> to be true.
 265    */
 266   int_type overflow(int_type c)
 267   {
 268     if (!traits_type::eq_int_type(c, traits_type::eof()))
 269     {
 270       if (pptr() == epptr())
 271       {
 272         std::size_t buffer_size = pptr() - gptr();
 273         if (buffer_size < max_size_ && max_size_ - buffer_size < buffer_delta)
 274         {
 275           reserve(max_size_ - buffer_size);
 276         }
 277         else
 278         {
 279           reserve(buffer_delta);
 280         }
 281       }
 282
 283       *pptr() = traits_type::to_char_type(c);
 284       pbump(1);
 285       return c;
 286     }
 287
 288     return traits_type::not_eof(c);
 289   }
 290
 291   void reserve(std::size_t n)
 292   {
 293     // Get current stream positions as offsets.
 294     std::size_t gnext = gptr() - &buffer_[0];
 295     std::size_t pnext = pptr() - &buffer_[0];
 296     std::size_t pend = epptr() - &buffer_[0];
 297
 298     // Check if there is already enough space in the put area.
 299     if (n <= pend - pnext)
 300     {
 301       return;
 302     }
 303
 304     // Shift existing contents of get area to start of buffer.
 305     if (gnext > 0)
 306     {
 307       pnext -= gnext;
 308       std::memmove(&buffer_[0], &buffer_[0] + gnext, pnext);
 309     }
 310
 311     // Ensure buffer is large enough to hold at least the specified size.
 312     if (n > pend - pnext)
 313     {
 314       if (n <= max_size_ && pnext <= max_size_ - n)
 315       {
 316         pend = pnext + n;
 317         buffer_.resize((std::max<std::size_t>)(pend, 1));
 318       }
 319       else
 320       {
 321         throw std::length_error("boost::asio::streambuf too long");
 322       }
 323     }
 324
 325     // Update stream positions.
 326     setg(&buffer_[0], &buffer_[0], &buffer_[0] + pnext);
 327     setp(&buffer_[0] + pnext, &buffer_[0] + pend);
 328   }
 329
 330 private:
 331   std::size_t max_size_;
 332   std::vector<char_type, Allocator> buffer_;
 333 };
 334
 335 } // namespace asio
 336 } // namespace boost
 337
 338 #include <boost/asio/detail/pop_options.hpp>
 339
 340 #endif // BOOST_ASIO_BASIC_STREAMBUF_HPP