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[section:DynamicBuffer DynamicBuffer] 11 12A dynamic buffer encapsulates memory storage that may be automatically resized 13as required, where the memory is divided into an input sequence followed by an 14output sequence. These memory regions are internal to the dynamic buffer, but 15direct access to the elements is provided to permit them to be efficiently used 16with I/O operations, such as the send or receive operations of a socket. Data 17written to the output sequence of a dynamic buffer object is appended to the 18input sequence of the same object. 19 20The interface to this concept is intended to permit the following 21implementation strategies: 22 23* A single contiguous octet array, which is reallocated as necessary to 24 accommodate changes in the size of the octet sequence. This is the 25 implementation approach currently offered by __flat_buffer__. 26 27* A sequence of one or more octet arrays, where each array is of the same 28 size. Additional octet array objects are appended to the sequence to 29 accommodate changes in the size of the octet sequence. 30 31* A sequence of one or more octet arrays of varying sizes. Additional octet 32 array objects are appended to the sequence to accommodate changes in the 33 size of the character sequence. This is the implementation approach 34 currently offered by __multi_buffer__. 35 36[heading Associated With] 37 38* `boost::asio::is_dynamic_buffer` 39* __ConstBufferSequence__ 40* __MutableBufferSequence__ 41 42[heading Requirements] 43 44* `D` denotes a dynamic buffer class. 45* `a` denotes a value of type `D`. 46* `c` denotes a (possibly const) value of type `D`. 47* `n` denotes a value of type `std::size_t`. 48* `T` denotes a type meeting the requirements for __ConstBufferSequence__. 49* `U` denotes a type meeting the requirements for __MutableBufferSequence__. 50 51[table Valid expressions 52[[Expression] [Type] [Semantics, Pre/Post-conditions]] 53[ 54 [`D::const_buffers_type`] 55 [`T`] 56 [ 57 This type represents the memory associated with the input sequence. 58 ] 59][ 60 [`D::mutable_buffers_type`] 61 [`U`] 62 [ 63 This type represents the memory associated with the output sequence. 64 ] 65][ 66 [`c.size()`] 67 [`std::size_t`] 68 [ 69 Returns the size, in bytes, of the input sequence. 70 ] 71][ 72 [`c.max_size()`] 73 [`std::size_t`] 74 [ 75 Returns the permitted maximum of the sum of the sizes of the input 76 sequence and output sequence. 77 ] 78][ 79 [`c.capacity()`] 80 [`std::size_t`] 81 [ 82 Returns the maximum sum of the sizes of the input sequence and output 83 sequence that the dynamic buffer can hold without requiring reallocation. 84 ] 85][ 86 [`c.data()`] 87 [`D::const_buffers_type`] 88 [ 89 Returns a constant buffer sequence u that represents the memory 90 associated with the input sequence, and where `buffer_size(u) == size()`. 91 ] 92][ 93 [`a.prepare(n)`] 94 [`D::mutable_buffers_type`] 95 [ 96 Returns a mutable buffer sequence u representing the output sequence, 97 and where `buffer_size(u) == n`. The dynamic buffer reallocates memory 98 as required. All constant or mutable buffer sequences previously 99 obtained using `data()` or `prepare()` are invalidated. 100 101 Throws: `length_error` if `size() + n` exceeds `max_size()`. 102 ] 103][ 104 [`a.commit(n)`] 105 [ ] 106 [ 107 Appends `n` bytes from the start of the output sequence to the end of 108 the input sequence. The remainder of the output sequence is discarded. 109 If `n` is greater than the size of the output sequence, the entire 110 output sequence is appended to the input sequence. All constant or 111 mutable buffer sequences previously obtained using `data()` or 112 `prepare()` are invalidated. 113 ] 114][ 115 [`a.consume(n)`] 116 [ ] 117 [ 118 Removes `n` bytes from beginning of the input sequence. If `n` is 119 greater than the size of the input sequence, the entire input sequence 120 is removed. All constant or mutable buffer sequences previously 121 obtained using `data()` or `prepare()` are invalidated. 122 ] 123]] 124 125[heading Models] 126 127* [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`] 128* [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`] 129* [link beast.ref.boost__beast__flat_buffer `flat_buffer`] 130* [link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`] 131* [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`] 132* [link beast.ref.boost__beast__static_buffer `static_buffer`] 133* [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`] 134* [link beast.ref.boost__beast__multi_buffer `multi_buffer`] 135 136[endsect] 137