ceph/src/boost/boost/beast/core/static_buffer.hpp

   1 //
   2 // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
   3 //
   4 // Distributed under the Boost Software License, Version 1.0. (See accompanying
   5 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6 //
   7 // Official repository: https://github.com/boostorg/beast
   8 //
   9
  10 #ifndef BOOST_BEAST_STATIC_BUFFER_HPP
  11 #define BOOST_BEAST_STATIC_BUFFER_HPP
  12
  13 #include <boost/beast/core/detail/config.hpp>
  14 #include <boost/beast/core/detail/buffers_pair.hpp>
  15 #include <boost/asio/buffer.hpp>
  16 #include <cstddef>
  17
  18 namespace boost {
  19 namespace beast {
  20
  21 /** A dynamic buffer providing a fixed size, circular buffer.
  22
  23     A dynamic buffer encapsulates memory storage that may be
  24     automatically resized as required, where the memory is
  25     divided into two regions: readable bytes followed by
  26     writable bytes. These memory regions are internal to
  27     the dynamic buffer, but direct access to the elements
  28     is provided to permit them to be efficiently used with
  29     I/O operations.
  30
  31     Objects of this type meet the requirements of <em>DynamicBuffer</em>
  32     and have the following additional properties:
  33
  34     @li A mutable buffer sequence representing the readable
  35     bytes is returned by @ref data when `this` is non-const.
  36
  37     @li Buffer sequences representing the readable and writable
  38     bytes, returned by @ref data and @ref prepare, may have
  39     length up to two.
  40
  41     @li All operations execute in constant time.
  42
  43     @li Ownership of the underlying storage belongs to the
  44     derived class.
  45
  46     @note Variables are usually declared using the template class
  47     @ref static_buffer; however, to reduce the number of template
  48     instantiations, objects should be passed `static_buffer_base&`.
  49
  50     @see static_buffer
  51 */
  52 class static_buffer_base
  53 {
  54     char* begin_;
  55     std::size_t in_off_ = 0;
  56     std::size_t in_size_ = 0;
  57     std::size_t out_size_ = 0;
  58     std::size_t capacity_;
  59
  60     static_buffer_base(static_buffer_base const& other) = delete;
  61     static_buffer_base& operator=(static_buffer_base const&) = delete;
  62
  63 public:
  64     /** Constructor
  65
  66         This creates a dynamic buffer using the provided storage area.
  67
  68         @param p A pointer to valid storage of at least `n` bytes.
  69
  70         @param size The number of valid bytes pointed to by `p`.
  71     */
  72     BOOST_BEAST_DECL
  73     static_buffer_base(void* p, std::size_t size) noexcept;
  74
  75     /** Clear the readable and writable bytes to zero.
  76
  77         This function causes the readable and writable bytes
  78         to become empty. The capacity is not changed.
  79
  80         Buffer sequences previously obtained using @ref data or
  81         @ref prepare become invalid.
  82
  83         @esafe
  84
  85         No-throw guarantee.
  86     */
  87     BOOST_BEAST_DECL
  88     void
  89     clear() noexcept;
  90
  91     //--------------------------------------------------------------------------
  92
  93 #if BOOST_BEAST_DOXYGEN
  94     /// The ConstBufferSequence used to represent the readable bytes.
  95     using const_buffers_type = __implementation_defined__;
  96
  97     /// The MutableBufferSequence used to represent the readable bytes.
  98     using mutable_data_type = __implementation_defined__;
  99
 100     /// The MutableBufferSequence used to represent the writable bytes.
 101     using mutable_buffers_type = __implementation_defined__;
 102 #else
 103     using const_buffers_type   = detail::buffers_pair<false>;
 104     using mutable_data_type    = detail::buffers_pair<true>;
 105     using mutable_buffers_type = detail::buffers_pair<true>;
 106 #endif
 107
 108     /// Returns the number of readable bytes.
 109     std::size_t
 110     size() const noexcept
 111     {
 112         return in_size_;
 113     }
 114
 115     /// Return the maximum number of bytes, both readable and writable, that can ever be held.
 116     std::size_t
 117     max_size() const noexcept
 118     {
 119         return capacity_;
 120     }
 121
 122     /// Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation.
 123     std::size_t
 124     capacity() const noexcept
 125     {
 126         return capacity_;
 127     }
 128
 129     /// Returns a constant buffer sequence representing the readable bytes
 130     BOOST_BEAST_DECL
 131     const_buffers_type
 132     data() const noexcept;
 133
 134     /// Returns a constant buffer sequence representing the readable bytes
 135     const_buffers_type
 136     cdata() const noexcept
 137     {
 138         return data();
 139     }
 140
 141     /// Returns a mutable buffer sequence representing the readable bytes
 142     BOOST_BEAST_DECL
 143     mutable_data_type
 144     data() noexcept;
 145
 146     /** Returns a mutable buffer sequence representing writable bytes.
 147
 148         Returns a mutable buffer sequence representing the writable
 149         bytes containing exactly `n` bytes of storage. Memory may be
 150         reallocated as needed.
 151
 152         All buffers sequences previously obtained using
 153         @ref data or @ref prepare are invalidated.
 154
 155         @param n The desired number of bytes in the returned buffer
 156         sequence.
 157
 158         @throws std::length_error if `size() + n` exceeds `max_size()`.
 159
 160         @esafe
 161
 162         Strong guarantee.
 163     */
 164     BOOST_BEAST_DECL
 165     mutable_buffers_type
 166     prepare(std::size_t n);
 167
 168     /** Append writable bytes to the readable bytes.
 169
 170         Appends n bytes from the start of the writable bytes to the
 171         end of the readable bytes. The remainder of the writable bytes
 172         are discarded. If n is greater than the number of writable
 173         bytes, all writable bytes are appended to the readable bytes.
 174
 175         All buffers sequences previously obtained using
 176         @ref data or @ref prepare are invalidated.
 177
 178         @param n The number of bytes to append. If this number
 179         is greater than the number of writable bytes, all
 180         writable bytes are appended.
 181
 182         @esafe
 183
 184         No-throw guarantee.
 185     */
 186     BOOST_BEAST_DECL
 187     void
 188     commit(std::size_t n) noexcept;
 189
 190     /** Remove bytes from beginning of the readable bytes.
 191
 192         Removes n bytes from the beginning of the readable bytes.
 193
 194         All buffers sequences previously obtained using
 195         @ref data or @ref prepare are invalidated.
 196
 197         @param n The number of bytes to remove. If this number
 198         is greater than the number of readable bytes, all
 199         readable bytes are removed.
 200
 201         @esafe
 202
 203         No-throw guarantee.
 204     */
 205     BOOST_BEAST_DECL
 206     void
 207     consume(std::size_t n) noexcept;
 208 };
 209
 210 //------------------------------------------------------------------------------
 211
 212 /** A dynamic buffer providing a fixed size, circular buffer.
 213
 214     A dynamic buffer encapsulates memory storage that may be
 215     automatically resized as required, where the memory is
 216     divided into two regions: readable bytes followed by
 217     writable bytes. These memory regions are internal to
 218     the dynamic buffer, but direct access to the elements
 219     is provided to permit them to be efficiently used with
 220     I/O operations.
 221
 222     Objects of this type meet the requirements of <em>DynamicBuffer</em>
 223     and have the following additional properties:
 224
 225     @li A mutable buffer sequence representing the readable
 226     bytes is returned by @ref data when `this` is non-const.
 227
 228     @li Buffer sequences representing the readable and writable
 229     bytes, returned by @ref data and @ref prepare, may have
 230     length up to two.
 231
 232     @li All operations execute in constant time.
 233
 234     @tparam N The number of bytes in the internal buffer.
 235
 236     @note To reduce the number of template instantiations when passing
 237     objects of this type in a deduced context, the signature of the
 238     receiving function should use @ref static_buffer_base instead.
 239
 240     @see static_buffer_base
 241 */
 242 template<std::size_t N>
 243 class static_buffer : public static_buffer_base
 244 {
 245     char buf_[N];
 246
 247 public:
 248     /// Constructor
 249     static_buffer() noexcept
 250         : static_buffer_base(buf_, N)
 251     {
 252     }
 253
 254     /// Constructor
 255     static_buffer(static_buffer const&) noexcept;
 256
 257     /// Assignment
 258     static_buffer& operator=(static_buffer const&) noexcept;
 259
 260     /// Returns the @ref static_buffer_base portion of this object
 261     static_buffer_base&
 262     base() noexcept
 263     {
 264         return *this;
 265     }
 266
 267     /// Returns the @ref static_buffer_base portion of this object
 268     static_buffer_base const&
 269     base() const noexcept
 270     {
 271         return *this;
 272     }
 273
 274     /// Return the maximum sum of the input and output sequence sizes.
 275     std::size_t constexpr
 276     max_size() const noexcept
 277     {
 278         return N;
 279     }
 280
 281     /// Return the maximum sum of input and output sizes that can be held without an allocation.
 282     std::size_t constexpr
 283     capacity() const noexcept
 284     {
 285         return N;
 286     }
 287 };
 288
 289 } // beast
 290 } // boost
 291
 292 #include <boost/beast/core/impl/static_buffer.hpp>
 293 #ifdef BOOST_BEAST_HEADER_ONLY
 294 #include <boost/beast/core/impl/static_buffer.ipp>
 295 #endif
 296
 297 #endif