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 writable bytes.
  98     using mutable_buffers_type = __implementation_defined__;
  99 #else
 100     using const_buffers_type   = detail::buffers_pair<false>;
 101
 102 #ifdef BOOST_BEAST_ALLOW_DEPRECATED
 103     using mutable_data_type    = detail::buffers_pair<true>;
 104 #endif
 105
 106     using mutable_buffers_type = detail::buffers_pair<true>;
 107 #endif
 108
 109     /// Returns the number of readable bytes.
 110     std::size_t
 111     size() const noexcept
 112     {
 113         return in_size_;
 114     }
 115
 116     /// Return the maximum number of bytes, both readable and writable, that can ever be held.
 117     std::size_t
 118     max_size() const noexcept
 119     {
 120         return capacity_;
 121     }
 122
 123     /// Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation.
 124     std::size_t
 125     capacity() const noexcept
 126     {
 127         return capacity_;
 128     }
 129
 130     /// Returns a constant buffer sequence representing the readable bytes
 131     BOOST_BEAST_DECL
 132     const_buffers_type
 133     data() const noexcept;
 134
 135     /// Returns a constant buffer sequence representing the readable bytes
 136     const_buffers_type
 137     cdata() const noexcept
 138     {
 139         return data();
 140     }
 141
 142     /// Returns a mutable buffer sequence representing the readable bytes
 143     BOOST_BEAST_DECL
 144     mutable_buffers_type
 145     data() noexcept;
 146
 147     /** Returns a mutable buffer sequence representing writable bytes.
 148
 149         Returns a mutable buffer sequence representing the writable
 150         bytes containing exactly `n` bytes of storage. Memory may be
 151         reallocated as needed.
 152
 153         All buffers sequences previously obtained using
 154         @ref data or @ref prepare are invalidated.
 155
 156         @param n The desired number of bytes in the returned buffer
 157         sequence.
 158
 159         @throws std::length_error if `size() + n` exceeds `max_size()`.
 160
 161         @esafe
 162
 163         Strong guarantee.
 164     */
 165     BOOST_BEAST_DECL
 166     mutable_buffers_type
 167     prepare(std::size_t n);
 168
 169     /** Append writable bytes to the readable bytes.
 170
 171         Appends n bytes from the start of the writable bytes to the
 172         end of the readable bytes. The remainder of the writable bytes
 173         are discarded. If n is greater than the number of writable
 174         bytes, all writable bytes are appended to the readable bytes.
 175
 176         All buffers sequences previously obtained using
 177         @ref data or @ref prepare are invalidated.
 178
 179         @param n The number of bytes to append. If this number
 180         is greater than the number of writable bytes, all
 181         writable bytes are appended.
 182
 183         @esafe
 184
 185         No-throw guarantee.
 186     */
 187     BOOST_BEAST_DECL
 188     void
 189     commit(std::size_t n) noexcept;
 190
 191     /** Remove bytes from beginning of the readable bytes.
 192
 193         Removes n bytes from the beginning of the readable bytes.
 194
 195         All buffers sequences previously obtained using
 196         @ref data or @ref prepare are invalidated.
 197
 198         @param n The number of bytes to remove. If this number
 199         is greater than the number of readable bytes, all
 200         readable bytes are removed.
 201
 202         @esafe
 203
 204         No-throw guarantee.
 205     */
 206     BOOST_BEAST_DECL
 207     void
 208     consume(std::size_t n) noexcept;
 209 };
 210
 211 //------------------------------------------------------------------------------
 212
 213 /** A dynamic buffer providing a fixed size, circular buffer.
 214
 215     A dynamic buffer encapsulates memory storage that may be
 216     automatically resized as required, where the memory is
 217     divided into two regions: readable bytes followed by
 218     writable bytes. These memory regions are internal to
 219     the dynamic buffer, but direct access to the elements
 220     is provided to permit them to be efficiently used with
 221     I/O operations.
 222
 223     Objects of this type meet the requirements of <em>DynamicBuffer</em>
 224     and have the following additional properties:
 225
 226     @li A mutable buffer sequence representing the readable
 227     bytes is returned by @ref data when `this` is non-const.
 228
 229     @li Buffer sequences representing the readable and writable
 230     bytes, returned by @ref data and @ref prepare, may have
 231     length up to two.
 232
 233     @li All operations execute in constant time.
 234
 235     @tparam N The number of bytes in the internal buffer.
 236
 237     @note To reduce the number of template instantiations when passing
 238     objects of this type in a deduced context, the signature of the
 239     receiving function should use @ref static_buffer_base instead.
 240
 241     @see static_buffer_base
 242 */
 243 template<std::size_t N>
 244 class static_buffer : public static_buffer_base
 245 {
 246     char buf_[N];
 247
 248 public:
 249     /// Constructor
 250     static_buffer() noexcept
 251         : static_buffer_base(buf_, N)
 252     {
 253     }
 254
 255     /// Constructor
 256     static_buffer(static_buffer const&) noexcept;
 257
 258     /// Assignment
 259     static_buffer& operator=(static_buffer const&) noexcept;
 260
 261     /// Returns the @ref static_buffer_base portion of this object
 262     static_buffer_base&
 263     base() noexcept
 264     {
 265         return *this;
 266     }
 267
 268     /// Returns the @ref static_buffer_base portion of this object
 269     static_buffer_base const&
 270     base() const noexcept
 271     {
 272         return *this;
 273     }
 274
 275     /// Return the maximum sum of the input and output sequence sizes.
 276     std::size_t constexpr
 277     max_size() const noexcept
 278     {
 279         return N;
 280     }
 281
 282     /// Return the maximum sum of input and output sizes that can be held without an allocation.
 283     std::size_t constexpr
 284     capacity() const noexcept
 285     {
 286         return N;
 287     }
 288 };
 289
 290 } // beast
 291 } // boost
 292
 293 #include <boost/beast/core/impl/static_buffer.hpp>
 294 #ifdef BOOST_BEAST_HEADER_ONLY
 295 #include <boost/beast/core/impl/static_buffer.ipp>
 296 #endif
 297
 298 #endif