boost_beast/doc/3_3_buffers.qbk

[/
    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 Buffer Types]

__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 this `streambuf`
interface into the __DynamicBuffer__ concept. Beast algorithms which require
resizable buffers accept dynamic buffer objects as templated parameters.
These metafunctions check if types match the buffer concepts:

[table Buffer Type Checks
[[Name][Description]]
[[
    [link beast.ref.beast__is_dynamic_buffer `is_dynamic_buffer`]
][
    Determine if a type meets the requirements of __DynamicBuffer__.
]]
[[
    [link beast.ref.beast__is_const_buffer_sequence `is_const_buffer_sequence`]
][
    Determine if a type meets the requirements of __ConstBufferSequence__.
]]
[[
    [link beast.ref.beast__is_mutable_buffer_sequence `is_mutable_buffer_sequence`]
][
    Determine if a type meets the requirements of __MutableBufferSequence__.
]]
]

Beast provides several dynamic buffer implementations for a variety
of scenarios:

[table Dynamic Buffer Implementations
[[Name][Description]]
[[
    [link beast.ref.beast__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.beast__drain_buffer `drain_buffer`]
][
    A drain buffer has a small internal buffer and maximum size that
    uses no dynamic allocation. It always has a size of zero, and
    silently discards its input. This buffer may be passed to functions
    which store data in a dynamic buffer when the caller wishes to
    efficiently discard the data.
]]
[[
    [link beast.ref.beast__flat_buffer `flat_buffer`]
    [link beast.ref.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
    [@http://en.cppreference.com/w/cpp/concept/AllocatorAwareContainer [*AllocatorAwareContainer]].
]]
[[
    [link beast.ref.beast__multi_buffer `multi_buffer`]
    [link beast.ref.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
    [@http://en.cppreference.com/w/cpp/concept/AllocatorAwareContainer [*AllocatorAwareContainer]].
]]
[[
    [link beast.ref.beast__static_buffer `static_buffer`]
    [link beast.ref.beast__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 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.beast__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.beast__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.beast__buffer_cat `buffer_cat`].
]]
[[
    [link beast.ref.beast__buffer_prefix `buffer_prefix`]
][
    This function returns a new buffer or buffer sequence which represents
    a prefix of the original buffers.
]]
[[
    [link beast.ref.beast__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.beast__buffer_prefix.overload3 `buffer_prefix`].
]]
[[
    [link beast.ref.beast__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.beast__buffers `buffers`]
][
    This function wraps a __ConstBufferSequence__ so it may be
    used with `operator<<` and `std::ostream`.
]]
[[
    [link beast.ref.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.
]]
]

[endsect]