forked from boostorg/beast
150 lines
5.3 KiB
Plaintext
150 lines
5.3 KiB
Plaintext
[/
|
|
Copyright (c) 2013-2017 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:buffers Using Buffers]
|
|
|
|
__Asio__ provides the __ConstBufferSequence__ and __MutableBufferSequence__
|
|
concepts, whose models provide ranges of buffers, as well as the __streambuf__
|
|
class which encapsulates memory storage that may be automatically resized as
|
|
required, where the memory is divided into an input sequence followed by an
|
|
output sequence. The Networking TS (__N4588__) generalizes the `streambuf`
|
|
interface into the __DynamicBuffer__ concept. Beast algorithms which require
|
|
resizable buffers accept as parameters dynamic buffer objects. These
|
|
metafunctions check types against these buffer concepts:
|
|
|
|
[table Buffer Type Checks
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.is_const_buffer_sequence `is_const_buffer_sequence`]
|
|
][
|
|
Determine if a type meets the requirements of __ConstBufferSequence__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_mutable_buffer_sequence `is_mutable_buffer_sequence`]
|
|
][
|
|
Determine if a type meets the requirements of __MutableBufferSequence__.
|
|
]]
|
|
[[
|
|
[link beast.ref.is_dynamic_buffer `is_dynamic_buffer`]
|
|
][
|
|
Determine if a type meets the requirements of __DynamicBuffer__.
|
|
]]
|
|
]
|
|
|
|
To suit various needs, several implementation of dynamic buffer are available:
|
|
|
|
[table Dynamic Buffer Implementations
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.buffers_adapter `buffers_adapter`]
|
|
][
|
|
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.flat_buffer `flat_buffer`]
|
|
[link beast.ref.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
|
|
supports the standard allocator model.
|
|
]]
|
|
[[
|
|
[link beast.ref.multi_buffer `multi_buffer`]
|
|
[link beast.ref.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 supports the standard allocator model.
|
|
]]
|
|
[[
|
|
[link beast.ref.static_buffer `static_buffer`]
|
|
[link beast.ref.static_buffer `static_buffer_n`]
|
|
][
|
|
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.
|
|
]]
|
|
]
|
|
|
|
Network applications frequently need to manipulate buffer sequences. To
|
|
facilitate working with buffers the library treats these sequences as
|
|
a special type of range. Algorithms and wrappers are provided which
|
|
transform these buffer sequences 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
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.buffer_cat `buffer_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.buffer_cat_view `buffer_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.buffer_cat `buffer_cat`].
|
|
]]
|
|
[[
|
|
[link beast.ref.buffer_prefix `buffer_prefix`]
|
|
][
|
|
This function returns a new buffer or buffer sequence which represents
|
|
a prefix of the original buffers.
|
|
]]
|
|
[[
|
|
[link beast.ref.buffer_prefix_view `buffer_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.buffer_prefix `buffer_prefix`].
|
|
]]
|
|
[[
|
|
[link beast.ref.consuming_buffers `consuming_buffers`]
|
|
][
|
|
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.
|
|
]]
|
|
]
|
|
|
|
These two functions facilitate buffer interoperability with standard
|
|
output streams.
|
|
|
|
[table Buffer Output Streams
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.buffers `buffers`]
|
|
][
|
|
This function wraps a __ConstBufferSequence__ so it may be
|
|
used with `operator<<` and `std::ostream`.
|
|
]]
|
|
[[
|
|
[link beast.ref.ostream `ostream`]
|
|
][
|
|
This function returns a `std::ostream` which wraps a dynamic buffer.
|
|
Characters sent to the stream using `operator<<` is stored in the
|
|
dynamic buffer.
|
|
]]
|
|
]
|
|
|
|
[endsect]
|