boost_beast/doc/concept/BodyReader.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:BodyReader BodyReader]

A [*BodyReader] provides an 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 [*BodyReader] 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.

In this table:

* `X` denotes a type meeting the requirements of [*BodyReader].

* `B` denotes a __Body__ where
      `std::is_same<X, B::reader>::value == true`.

* `a` denotes a value of type `X`.

* `m` denotes a value of type `message const&` where
      `std::is_same<decltype(m.body), Body::value_type>:value == true`.

* `ec` is a value of type [link beast.ref.beast__error_code `error_code&`].

* `R<T>` is the type `boost::optional<std::pair<T, bool>>`.

[table BodyReader requirements
[[expression] [type] [semantics, pre/post-conditions]]
[
    [`X::const_buffers_type`]
    []
    [
        A type which meets the requirements of __ConstBufferSequence__.
        This is the type of buffer returned by `X::get`.
    ]
][
    [`X(m,ec);`]
    []
    [
        Constructible from `m`. The lifetime of `m` is guaranteed
        to end no earlier than after the `X` 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)`]
    [`R<X::const_buffers_type>`]
    [
        Called repeatedly 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. 
    ]
][
    [`is_body_reader<B>`]
    [`std::true_type`]
    [
        An alias for `std::true_type` for `B`, otherwise an alias
        for `std::false_type`.
    ]
]
]

[heading Exemplar]

[concept_BodyReader]

[endsect]