9be88fb192
This change adds a new set of type requirements for dynamic buffers,
DynamicBuffer_v2, which supports copy construction. These new type
requirements enable dynamic buffers to be used as arguments to
user-defined composed operations, where the same dynamic buffer object
is used repeatedly for multiple underlying operations. For example:
template <typename DynamicBuffer>
void echo_line(tcp::socket& sock, DynamicBuffer buf)
{
n = boost::asio::read_until(sock, buf, '\n');
boost::asio::write(sock, buf, boost::asio::transfer_exactly(n));
}
The original DynamicBuffer type requirements have been renamed to
DynamicBuffer_v1.
New type traits is_dynamic_buffer_v1 and is_dynamic_buffer_v2 have been
added to test for conformance to DynamicBuffer_v1 and DynamicBuffer_v2
respectively. The existing is_dynamic_buffer trait has been retained and
delegates to is_dynamic_buffer_v1, unless BOOST_ASIO_NO_DYNAMIC_BUFFER_V1
is defined, in which case it delegates to is_dynamic_buffer_v2.
The dynamic_string_buffer and dynamic_vector buffer classes conform to
both DynamicBuffer_v1 and DynamicBuffer_v2 requirements.
When BOOST_ASIO_NO_DYNAMIC_BUFFER_V1 is defined, all support for
DynamicBuffer_v1 types and functions is #ifdef-ed out. Support for using
basic_streambuf with the read, async_read, read_until, async_read_until,
write, and async_write functions is also disabled as a consequence.
This change should have no impact on existing source code that simply
uses dynamic buffers in conjunction with asio's composed operations,
such as:
string data;
// ...
size_t n = boost::asio::read_until(my_socket
boost::asio::dynamic_buffer(data, MY_MAX),
'\n');
95 lines
3.1 KiB
Plaintext
95 lines
3.1 KiB
Plaintext
[/
|
|
/ Copyright (c) 2003-2019 Christopher M. Kohlhoff (chris at kohlhoff 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_v2 Dynamic buffer requirements (version 2)]
|
|
|
|
A dynamic buffer encapsulates memory storage that may be automatically resized
|
|
as required.
|
|
|
|
A dynamic buffer type `X` shall satisfy the requirements of `CopyConstructible`
|
|
(C++ Std, [copyconstructible]) types in addition to those listed below.
|
|
|
|
In the table below, `X` denotes a dynamic buffer class, `x` denotes a value of
|
|
type `X&`, `x1` denotes values of type `const X&`, `pos` and `n` denote values
|
|
of type `size_t`, and `u` denotes an identifier.
|
|
|
|
[table DynamicBuffer_v2 requirements
|
|
[[expression] [type] [assertion/note\npre/post-conditions]]
|
|
[
|
|
[`X::const_buffers_type`]
|
|
[type meeting [link boost_asio.reference.ConstBufferSequence ConstBufferSequence]
|
|
requirements.]
|
|
[This type represents the underlying memory as a sequence of @c const_buffer
|
|
objects.]
|
|
]
|
|
[
|
|
[`X::mutable_buffers_type`]
|
|
[type meeting [link boost_asio.reference.MutableBufferSequence MutableBufferSequence]
|
|
requirements.]
|
|
[This type represents the underlying memory as a sequence of @c
|
|
mutable_buffer objects.]
|
|
]
|
|
[
|
|
[`x1.size()`]
|
|
[`size_t`]
|
|
[Returns the size, in bytes, of the underlying memory.]
|
|
]
|
|
[
|
|
[`x1.max_size()`]
|
|
[`size_t`]
|
|
[Returns the permitted maximum size of the underlying memory.]
|
|
]
|
|
[
|
|
[`x1.capacity()`]
|
|
[`size_t`]
|
|
[Returns the maximum size to which the underlying memory can grow without
|
|
requiring reallocation.]
|
|
]
|
|
[
|
|
[`x1.data(pos, n)`]
|
|
[`X::const_buffers_type`]
|
|
[Returns a constant buffer sequence `u` that represents the underlying
|
|
memory beginning at offset `pos`, and where `buffer_size(u) <= n`.]
|
|
]
|
|
[
|
|
[`x.data(pos, n)`]
|
|
[`X::mutable_buffers_type`]
|
|
[Returns a mutable buffer sequence `u` that represents the underlying
|
|
memory beginning at offset `pos`, and where `buffer_size(u) <= n`.]
|
|
]
|
|
[
|
|
[`x.grow(n)`]
|
|
[]
|
|
[Requires: `size() + n <= max_size()`.\n
|
|
\n
|
|
Extends the underlying memory to accommodate `n` additional bytes at the
|
|
end. The dynamic buffer reallocates memory as required. All constant or
|
|
mutable buffer sequences previously obtained using `data()` are
|
|
invalidated.\n
|
|
\n
|
|
Throws: `length_error` if `size() + n > max_size()`.]
|
|
]
|
|
[
|
|
[`x.shrink(n)`]
|
|
[]
|
|
[Removes `n` bytes from the end of the underlying memory. If `n` is greater
|
|
than the size of the underlying memory, the entire underlying memory is
|
|
emptied. All constant or mutable buffer sequences previously obtained
|
|
using `data()` are invalidated.]
|
|
]
|
|
[
|
|
[`x.consume(n)`]
|
|
[]
|
|
[Removes `n` bytes from the beginning of the underlying memory. If `n` is
|
|
greater than the size of the underlying memory, the entire underlying memory
|
|
is emptied. All constant or mutable buffer sequences previously obtained
|
|
using `data()` are invalidated.]
|
|
]
|
|
]
|
|
|
|
[endsect]
|