[/
    Copyright (c) 2016-2019 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:BodyWriter BodyWriter]

A [*BodyWriter] provides an
[@https://en.wikipedia.org/wiki/Online_algorithm online algorithm]
to obtain a sequence of zero
or more buffers from a body during serialization. The implementation creates
an instance of this type when needed, and calls into it one or more times to
retrieve buffers holding body octets. The interface of [*BodyWriter] is
intended to obtain buffers for these scenarios:

* A body that does not entirely fit in memory.
* A body produced incrementally from coroutine output.
* A body represented by zero or more buffers already in memory.
* A body whose size is not known ahead of time.
* Body data generated dynamically from other threads.
* Body data computed algorithmically.

[heading Associated Types]

* [link beast.ref.boost__beast__http__is_body_writer `is_body_writer`]
* __Body__

[heading Requirements]

[warning
    These requirements may undergo non-backward compatible
    changes in subsequent versions.
]

In this table:

* `W` denotes a type meeting the requirements of [*BodyWriter].
* `B` denotes a __Body__ where
      `std::is_same<W, B::writer>::value == true`.
* `a` denotes a value of type `W`.
* `h` denotes a const value of type `header<isRequest, Fields> const&`.
* `v` denotes a possibly const value of type `Body::value_type&`.
* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`].
* `W<T>` is the type `boost::optional<std::pair<T, bool>>`.

[table Valid expressions
[[Expression] [Type] [Semantics, Pre/Post-conditions]]
[
    [`W::const_buffers_type`]
    []
    [
        A type which meets the requirements of __ConstBufferSequence__.
        This is the type of buffer returned by `W::get`.
    ]
][
    [`W{h,v};`]
    []
    [
        Constructible from `h` and `v`. The lifetime of `h` and `v`
        are guaranteed to end no earlier than after the `W` is destroyed.
        The writer shall not access the contents of `h` or `v` before
        the first call to `init`, permitting lazy construction of the
        message.

        The constructor may optionally require that `h` and `v` are
        `const` references, with these consequences:

        * If `W` requires that `h` and `v` are const references, then
        the corresponding serializer constructors for messages with this
        body type will will accept a const reference to a message,
        otherwise:

        * If `W` requires that `h` and `v` are non-const references,
        then the corresponding serializer constructors for messages with
        this body type will require a non-const reference to a message.
    ]
][
    [`a.init(ec)`]
    []
    [
        Called once to fully initialize the object before any calls to
        `get`. The message body becomes valid before entering this function,
        and remains valid until the writer is destroyed.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
][
    [`a.get(ec)`]
    [`W<W::const_buffers_type>`]
    [
        Called one or more times after `init` succeeds. This function
        returns `boost::none` if all buffers representing the body have
        been returned in previous calls or if it sets `ec` to indicate an
        error. Otherwise, if there are buffers remaining the function
        should return a pair with the first element containing a non-zero
        length buffer sequence representing the next set of octets in
        the body, while the second element is a `bool` meaning `true`
        if there may be additional buffers returned on a subsequent call,
        or `false` if the buffer returned on this call is the last
        buffer representing the body.
        The function will ensure that `!ec` is `true` if there was
        no error or set to the appropriate error code if there was one. 
    ]
]]

[heading Exemplar]

[concept_BodyWriter]

[heading Models]

* [link beast.ref.boost__beast__http__basic_dynamic_body.writer `basic_dynamic_body::writer`]
* [link beast.ref.boost__beast__http__basic_file_body__writer `basic_file_body::writer`]
* [link beast.ref.boost__beast__http__basic_string_body.writer `basic_string_body::writer`]
* [link beast.ref.boost__beast__http__buffer_body.writer `buffer_body::writer`]
* [link beast.ref.boost__beast__http__empty_body.writer `empty_body::writer`]
* [link beast.ref.boost__beast__http__span_body.writer `span_body::writer`]
* [link beast.ref.boost__beast__http__vector_body.writer `vector_body::writer`]

[endsect]