mirror of
https://github.com/Xahau/xahaud.git
synced 2025-11-22 11:35:49 +00:00
50b5dab5df
Conform to the Networking TS by renaming the Streambuf concept to DynamicBuffer in all places. Values of types meeting the requirements of DynamicBuffer are renamed to dynabuf. See: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4478.html#requirements.dynamic_buffers * Headers renamed * Formal parameter names renamed * Template argument types renamed * Documentation updated
126 lines
4.3 KiB
Plaintext
126 lines
4.3 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2016 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)
|
|
]
|
|
|
|
[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.
|
|
|
|
* 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 approached
|
|
currently offered by [link beast.ref.basic_streambuf `basic_streambuf`].
|
|
|
|
In the table below:
|
|
|
|
* `X` denotes a dynamic buffer class.
|
|
* `a` denotes a value of type `X`.
|
|
* `c` denotes a (possibly const) value of type `X`.
|
|
* `n` denotes a value of type `std::size_t`.
|
|
* `T` denotes a type meeting the requirements for [@http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/ConstBufferSequence.html `ConstBufferSequence`].
|
|
* `U` denotes a type meeting the requirements for [@http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/MutableBufferSequence.html `MutableBufferSequence`].
|
|
|
|
[table DynamicBuffer requirements
|
|
[[operation] [type] [semantics, pre/post-conditions]]
|
|
[
|
|
[`X::const_buffers_type`]
|
|
[`T`]
|
|
[
|
|
This type represents the memory associated with the input sequence.
|
|
]
|
|
]
|
|
[
|
|
[`X::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()`]
|
|
[`X::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)`]
|
|
[`X: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.
|
|
]
|
|
]
|
|
]
|
|
|
|
[endsect]
|