fdf64a4550
* dynamic_buffer_ref is removed, because Asio / Networking has introduced the DynamicBuffer_v2 concept which is incompatible with Beast's storage types. The next version of Beast (1.70) will provide changes to interoperate with Asio / Networking's new concepts.
217 lines
8.5 KiB
Plaintext
217 lines
8.5 KiB
Plaintext
[/
|
|
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 Buffer Types]
|
|
|
|
To facilitate working with instances of the __ConstBufferSequence__ and
|
|
__MutableBufferSequence__ concepts introduced in __Asio__, Beast treats
|
|
those sequences as a special type of range. The following algorithms and
|
|
wrappers are provided which transform these ranges efficiently using lazy
|
|
evaluation. No memory allocations are used in the transformations; instead,
|
|
they create lightweight iterators over the existing, unmodified memory
|
|
buffers. Control of buffers is retained by the caller; ownership is not
|
|
transferred.
|
|
|
|
[table Buffer Algorithms and Types
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffer_bytes `buffer_bytes`]
|
|
][
|
|
This is a more reliable version of
|
|
[@boost:/doc/html/boost_asio/reference/buffer_size.html `net::buffer_size`]
|
|
which is easier to use and also works for types which are convertible
|
|
to `net::const_buffer` or `net::mutable_buffer`.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_cat `buffers_cat`]
|
|
][
|
|
This functions returns a new buffer sequence which, when iterated,
|
|
traverses the sequence which would be formed if all of the input buffer
|
|
sequences were concatenated. With this routine, multiple calls to a
|
|
stream's `write_some` function may be combined into one, eliminating
|
|
expensive system calls.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_cat_view `buffers_cat_view`]
|
|
][
|
|
This class represents the buffer sequence formed by concatenating
|
|
two or more buffer sequences. This is type of object returned by
|
|
[link beast.ref.boost__beast__buffers_cat `buffers_cat`].
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_front `buffers_front`]
|
|
][
|
|
This function returns the first buffer in a buffer sequence,
|
|
or a buffer of size zero if the buffer sequence has no elements.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_prefix `buffers_prefix`]
|
|
][
|
|
This function returns a new buffer or buffer sequence which represents
|
|
a prefix of the original buffers.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_prefix_view `buffers_prefix_view`]
|
|
][
|
|
This class represents the buffer sequence formed from a prefix of
|
|
an existing buffer sequence. This is the type of buffer returned by
|
|
[link beast.ref.boost__beast__buffers_prefix `buffers_prefix`].
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_range `buffers_range`]
|
|
[link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`]
|
|
][
|
|
This function returns an iterable range representing the passed
|
|
buffer sequence. The values obtained when iterating the range
|
|
will always be a constant buffer, unless the underlying buffer
|
|
sequence is mutable, in which case the value obtained when iterating
|
|
will be a mutable buffer. It is intended as a notational convenience
|
|
when writing a ['range-for] statement over a buffer sequence.
|
|
|
|
The function
|
|
[link beast.ref.boost__beast__buffers_range_ref `buffers_range`]
|
|
maintains a copy of the buffer sequence, while
|
|
[link beast.ref.boost__beast__buffers_range_ref `buffers_range_ref`]
|
|
maintains a reference (in this case, the caller must ensure that
|
|
the lifetime of the referenced buffer sequence extends until the
|
|
range object is destroyed).
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_suffix `buffers_suffix`]
|
|
][
|
|
This class wraps the underlying memory of an existing buffer sequence
|
|
and presents a suffix of the original sequence. The length of the suffix
|
|
may be progressively shortened. This lets callers work with sequential
|
|
increments of a buffer sequence.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_to_string `buffers_to_string`]
|
|
][
|
|
This function converts a buffer sequence to a `std::string`. It can
|
|
be used for diagnostic purposes and tests.
|
|
]]
|
|
]
|
|
|
|
The __DynamicBuffer__ concept introduced in __Asio__ models a buffer
|
|
sequence which supports an owning, resizable range. Beast provides this
|
|
set of additional implementations of the dynamic buffer concept:
|
|
|
|
[table Dynamic Buffer Implementations
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_adaptor `buffers_adaptor`]
|
|
][
|
|
This wrapper adapts any __MutableBufferSequence__ into a
|
|
__DynamicBuffer__ with an upper limit on the total size of the input and
|
|
output areas equal to the size of the underlying mutable buffer sequence.
|
|
The implementation does not perform heap allocations.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__flat_buffer `flat_buffer`]
|
|
[link beast.ref.boost__beast__basic_flat_buffer `basic_flat_buffer`]
|
|
][
|
|
Guarantees that input and output areas are buffer sequences with
|
|
length one.
|
|
Upon construction an optional upper limit to the total size of the
|
|
input and output areas may be set.
|
|
The basic container is an
|
|
[@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [*AllocatorAwareContainer]].
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__multi_buffer `multi_buffer`]
|
|
[link beast.ref.boost__beast__basic_multi_buffer `basic_multi_buffer`]
|
|
][
|
|
Uses a sequence of one or more character arrays of varying sizes.
|
|
Additional character array objects are appended to the sequence to
|
|
accommodate changes in the size of the character sequence.
|
|
The basic container is an
|
|
[@https://en.cppreference.com/w/cpp/named_req/AllocatorAwareContainer [*AllocatorAwareContainer]].
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__flat_static_buffer `flat_static_buffer`]
|
|
[link beast.ref.boost__beast__flat_static_buffer_base `flat_static_buffer_base`]
|
|
][
|
|
Guarantees that input and output areas are buffer sequences with
|
|
length one.
|
|
Provides the facilities of a dynamic buffer, subject to an upper
|
|
limit placed on the total size of the input and output areas defined
|
|
by a constexpr template parameter. The storage for the sequences are
|
|
kept in the class; the implementation does not perform heap allocations.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__static_buffer `static_buffer`]
|
|
[link beast.ref.boost__beast__static_buffer_base `static_buffer_base`]
|
|
][
|
|
Provides the facilities of a circular dynamic buffer. subject to an
|
|
upper limit placed on the total size of the input and output areas
|
|
defined by a constexpr template parameter.
|
|
The implementation never moves memory during buffer operations.
|
|
The storage for the sequences are kept in the class; the implementation
|
|
does not perform heap allocations.
|
|
]]
|
|
]
|
|
|
|
These two functions facilitate buffer interoperability with standard
|
|
output streams.
|
|
|
|
[table Buffer Output Streams
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__make_printable `make_printable`]
|
|
][
|
|
This function wraps a __ConstBufferSequence__ so it may be
|
|
used with `operator<<` and `std::ostream`.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__ostream `ostream`]
|
|
][
|
|
This function returns a `std::ostream` which wraps a dynamic buffer.
|
|
Characters sent to the stream using `operator<<` are stored in the
|
|
dynamic buffer.
|
|
]]
|
|
]
|
|
|
|
These type traits are provided to facilitate writing compile-time
|
|
metafunctions which operate on buffers:
|
|
|
|
[table Buffer Algorithms and Types
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_iterator_type `buffers_iterator_type`]
|
|
][
|
|
This metafunction is used to determine the type of iterator
|
|
used by a particular buffer sequence.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__buffers_type `buffers_type`]
|
|
][
|
|
This metafunction is used to determine the underlying buffer type for
|
|
a list of buffer sequence. The equivalent type of the alias will vary
|
|
depending on the template type argument.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__is_const_buffer_sequence `is_const_buffer_sequence`]
|
|
][
|
|
This metafunction is used to determine if all of the specified types
|
|
meet the requirements of __ConstBufferSequence__. This type alias
|
|
will be `std::true_type` if each specified type meets the requirements,
|
|
otherwise, this type alias will be `std::false_type`.
|
|
]]
|
|
[[
|
|
[link beast.ref.boost__beast__is_mutable_buffer_sequence `is_mutable_buffer_sequence`]
|
|
][
|
|
This metafunction is used to determine if all of the specified types
|
|
meet the requirements of __MutableBufferSequence__. This type alias
|
|
will be `std::true_type` if each specified type meets the requirements,
|
|
otherwise, this type alias will be `std::false_type`.
|
|
]]
|
|
]
|
|
|
|
[endsect]
|