Beast Logo

PrevUpHomeNext

Buffer Types

Boost.Asio provides the ConstBufferSequence and MutableBufferSequence concepts, whose models provide ranges of buffers, as well as the boost::asio::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 4. Buffer Type Checks

Name

Description

is_dynamic_buffer

Determine if a type meets the requirements of DynamicBuffer.

is_const_buffer_sequence

Determine if a type meets the requirements of ConstBufferSequence.

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 5. Dynamic Buffer Implementations

Name

Description

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.

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.

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 AllocatorAwareContainer.

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 AllocatorAwareContainer.

flat_static_buffer 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.

static_buffer 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.


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 6. Buffer Algorithms and Types

Name

Description

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.

buffer_cat_view

This class represents the buffer sequence formed by concatenating two or more buffer sequences. This is type of object returned by buffer_cat.

buffer_front

This function returns the first buffer in a buffer sequence, or a buffer of size zero if the buffer sequence has no elements.

buffer_prefix

This function returns a new buffer or buffer sequence which represents a prefix of the original buffers.

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 buffer_prefix.

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 7. Buffer Output Streams

Name

Description

buffers

This function wraps a ConstBufferSequence so it may be used with operator<< and std::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.



PrevUpHomeNext