Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for a snapshot of the develop branch, built from commit 65ab21cc6f.
PrevUpHomeNext

BuffersGenerator

A BuffersGenerator provides a generalized interface for generating serialized data for sequential processing.

The generator will be asked to produce buffers. The consuming code will signal how much of the data has been consumed, and repeatedly query for buffers until no more data is available, or the generator indicates an error condition.

In this way, serializers can be adapted as BuffersGenerator, for example http::message_generator which provides a type-erased interface for a variety of concrete http message types.

Overloads of write and async_write operations are provided as free functions. These operations will consume the output of a BuffersGenerator and process the data by writing them to a SyncWriteStream or AsyncWriteStream respectively.

Associated Types
Requirements

In this table:

Table 1.41. Valid expressions

Expression

Type

Semantics, Pre/Post-conditions

G::const_buffers_type

A type which meets the requirements of ConstBufferSequence. This is the type of buffer returned by g.prepare(ec).

c.is_done()

bool

Called to ask the generator for its completion status.

A generator has completed when no new buffer will be produced and previously produced buffers have been fully consumed.

Note: The result of invoking prepare on g once it has completed is unspecified.

g.prepare(ec)

G::const_buffers_type

Called to ask the generator to produce buffers containing data for processing.

The returned value is the ConstBufferSequence representing unconsumed data.

The function will ensure that ec.failed() is false if there was no error or set to the appropriate error code if there was one.

If no unconsumed data is available, this operation shall make progress to eventually reach completion.

The result of invoking prepare after completion or encountered error(s) is defined by the generator implementation. It can not be assumed to be meaningful or safe to do so, in general.

The capacity of the buffer returned is defined by the generator implementation.

Note: Any buffers obtained by previous calls to prepare are invalidated.

g.consume(n)

This function is called to signal that the consumer (caller) of the generator has processed part of the data returned by the previous call to prepare.

The value of n indicates how much of the data processed (in bytes).

When n exceeds the number of bytes returned from the last call to prepare, consume shall behave as if n was equal to that number.

Remaining unconsumed data will be returned from subsequent calls to prepare.

Note: Any buffers obtained by previous calls to prepare are invalidated.

is_buffers_generator<G>

std::bool_constant

An alias for std::true_type for G, otherwise an alias for std::false_type.


Exemplar
// A buffer sequence generator
struct BuffersGenerator
{
    using const_buffers_type = net::const_buffer;

    bool is_done() const;
    const_buffers_type prepare( error_code& ec );
    void consume( std::size_t n );
};

static_assert(
    is_buffers_generator<BuffersGenerator>::value, "");
Models
Algorithms

PrevUpHomeNext