123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136 |
- [/
- Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com)
- Distributed under the Boost Software License, Version 1.0. (See accompanying
- file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
- Official repository: https://github.com/boostorg/beast
- ]
- [section:DynamicBuffer DynamicBuffer]
- A dynamic buffer encapsulates memory storage that may be automatically resized
- as required, where the memory is divided into an input sequence followed by an
- output sequence. These memory regions are internal to the dynamic buffer, but
- direct access to the elements is provided to permit them to be efficiently used
- with I/O operations, such as the send or receive operations of a socket. Data
- written to the output sequence of a dynamic buffer object is appended to the
- input sequence of the same object.
- The interface to this concept is intended to permit the following
- implementation strategies:
- * A single contiguous octet array, which is reallocated as necessary to
- accommodate changes in the size of the octet sequence. This is the
- implementation approach currently offered by __flat_buffer__.
- * A sequence of one or more octet arrays, where each array is of the same
- size. Additional octet array objects are appended to the sequence to
- accommodate changes in the size of the octet sequence.
- * A sequence of one or more octet arrays of varying sizes. Additional octet
- array objects are appended to the sequence to accommodate changes in the
- size of the character sequence. This is the implementation approach
- currently offered by __multi_buffer__.
- [heading Associated With]
- * `boost::asio::is_dynamic_buffer`
- * __ConstBufferSequence__
- * __MutableBufferSequence__
- [heading Requirements]
- * `D` denotes a dynamic buffer class.
- * `a` denotes a value of type `D`.
- * `c` denotes a (possibly const) value of type `D`.
- * `n` denotes a value of type `std::size_t`.
- * `T` denotes a type meeting the requirements for __ConstBufferSequence__.
- * `U` denotes a type meeting the requirements for __MutableBufferSequence__.
- [table Valid expressions
- [[Expression] [Type] [Semantics, Pre/Post-conditions]]
- [
- [`D::const_buffers_type`]
- [`T`]
- [
- This type represents the memory associated with the input sequence.
- ]
- ][
- [`D::mutable_buffers_type`]
- [`U`]
- [
- This type represents the memory associated with the output sequence.
- ]
- ][
- [`c.size()`]
- [`std::size_t`]
- [
- Returns the size, in bytes, of the input sequence.
- ]
- ][
- [`c.max_size()`]
- [`std::size_t`]
- [
- Returns the permitted maximum of the sum of the sizes of the input
- sequence and output sequence.
- ]
- ][
- [`c.capacity()`]
- [`std::size_t`]
- [
- Returns the maximum sum of the sizes of the input sequence and output
- sequence that the dynamic buffer can hold without requiring reallocation.
- ]
- ][
- [`c.data()`]
- [`D::const_buffers_type`]
- [
- Returns a constant buffer sequence u that represents the memory
- associated with the input sequence, and where `buffer_size(u) == size()`.
- ]
- ][
- [`a.prepare(n)`]
- [`D::mutable_buffers_type`]
- [
- Returns a mutable buffer sequence u representing the output sequence,
- and where `buffer_size(u) == n`. The dynamic buffer reallocates memory
- as required. All constant or mutable buffer sequences previously
- obtained using `data()` or `prepare()` are invalidated.
- Throws: `length_error` if `size() + n` exceeds `max_size()`.
- ]
- ][
- [`a.commit(n)`]
- [ ]
- [
- Appends `n` bytes from the start of the output sequence to the end of
- the input sequence. The remainder of the output sequence is discarded.
- If `n` is greater than the size of the output sequence, the entire
- output sequence is appended to the input sequence. All constant or
- mutable buffer sequences previously obtained using `data()` or
- `prepare()` are invalidated.
- ]
- ][
- [`a.consume(n)`]
- [ ]
- [
- Removes `n` bytes from beginning of the input sequence. If `n` is
- greater than the size of the input sequence, the entire input sequence
- is removed. All constant or mutable buffer sequences previously
- obtained using `data()` or `prepare()` are invalidated.
- ]
- ]]
- [heading Models]
- * [link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`]
- * [link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]
- * [link beast.ref.boost__beast__flat_buffer `flat_buffer`]
- * [link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]
- * [link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`]
- * [link beast.ref.boost__beast__static_buffer `static_buffer`]
- * [link beast.ref.boost__beast__static_buffer_base `static_buffer_base`]
- * [link beast.ref.boost__beast__multi_buffer `multi_buffer`]
- [endsect]
|