forked from boostorg/beast
147 lines
4.6 KiB
Plaintext
147 lines
4.6 KiB
Plaintext
[/
|
|
Copyright (c) 2016-2022 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:BuffersGenerator 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
|
|
[link beast.ref.boost__beast__http__message_generator
|
|
`http::message_generator`] which provides a type-erased interface for a variety
|
|
of concrete http message types.
|
|
|
|
Overloads of [link beast.ref.boost__beast__write `write`] and [link
|
|
beast.ref.boost__beast__async_write `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.
|
|
|
|
[heading Associated Types]
|
|
|
|
* [link beast.ref.boost__beast__is_buffers_generator `is_buffers_generator`]
|
|
* __ConstBufferSequence__
|
|
|
|
[heading Requirements]
|
|
|
|
In this table:
|
|
|
|
* `G` denotes a type meeting the requirements of [*BuffersGenerator].
|
|
* `g` denotes a value of type `G`.
|
|
* `c` denotes a possibly-const value of type `G`.
|
|
* `n` is a value of type `std::size_t`.
|
|
* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].
|
|
|
|
[table 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`.
|
|
]
|
|
]]
|
|
|
|
[heading 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, "");
|
|
```
|
|
|
|
[heading Models]
|
|
|
|
* [link beast.ref.boost__beast__http__message_generator `http::message_generator`]
|
|
|
|
[heading Algorithms]
|
|
|
|
* [link beast.ref.boost__beast__async_write `async_write`]
|
|
* [link beast.ref.boost__beast__write `write`]
|
|
|
|
[endsect]
|