1[/ 2 Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) 3 4 Distributed under the Boost Software License, Version 1.0. (See accompanying 5 file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 6 7 Official repository: https://github.com/boostorg/beast 8] 9 10[section:BodyWriter BodyWriter] 11 12A [*BodyWriter] provides an 13[@https://en.wikipedia.org/wiki/Online_algorithm online algorithm] 14to obtain a sequence of zero 15or more buffers from a body during serialization. The implementation creates 16an instance of this type when needed, and calls into it one or more times to 17retrieve buffers holding body octets. The interface of [*BodyWriter] is 18intended to obtain buffers for these scenarios: 19 20* A body that does not entirely fit in memory. 21* A body produced incrementally from coroutine output. 22* A body represented by zero or more buffers already in memory. 23* A body whose size is not known ahead of time. 24* Body data generated dynamically from other threads. 25* Body data computed algorithmically. 26 27[heading Associated Types] 28 29* [link beast.ref.boost__beast__http__is_body_writer `is_body_writer`] 30* __Body__ 31 32[heading Requirements] 33 34[warning 35 These requirements may undergo non-backward compatible 36 changes in subsequent versions. 37] 38 39In this table: 40 41* `W` denotes a type meeting the requirements of [*BodyWriter]. 42* `B` denotes a __Body__ where 43 `std::is_same<W, B::writer>::value == true`. 44* `a` denotes a value of type `W`. 45* `h` denotes a const value of type `header<isRequest, Fields> const&`. 46* `v` denotes a possibly const value of type `Body::value_type&`. 47* `ec` is a value of type [link beast.ref.boost__beast__error_code `error_code&`]. 48* `W<T>` is the type `boost::optional<std::pair<T, bool>>`. 49 50[table Valid expressions 51[[Expression] [Type] [Semantics, Pre/Post-conditions]] 52[ 53 [`W::const_buffers_type`] 54 [] 55 [ 56 A type which meets the requirements of __ConstBufferSequence__. 57 This is the type of buffer returned by `W::get`. 58 ] 59][ 60 [`W{h,v};`] 61 [] 62 [ 63 Constructible from `h` and `v`. The lifetime of `h` and `v` 64 are guaranteed to end no earlier than after the `W` is destroyed. 65 The writer shall not access the contents of `h` or `v` before 66 the first call to `init`, permitting lazy construction of the 67 message. 68 69 The constructor may optionally require that `h` and `v` are 70 `const` references, with these consequences: 71 72 * If `W` requires that `h` and `v` are const references, then 73 the corresponding serializer constructors for messages with this 74 body type will will accept a const reference to a message, 75 otherwise: 76 77 * If `W` requires that `h` and `v` are non-const references, 78 then the corresponding serializer constructors for messages with 79 this body type will require a non-const reference to a message. 80 ] 81][ 82 [`a.init(ec)`] 83 [] 84 [ 85 Called once to fully initialize the object before any calls to 86 `get`. The message body becomes valid before entering this function, 87 and remains valid until the writer is destroyed. 88 The function will ensure that `!ec` is `true` if there was 89 no error or set to the appropriate error code if there was one. 90 ] 91][ 92 [`a.get(ec)`] 93 [`W<W::const_buffers_type>`] 94 [ 95 Called one or more times after `init` succeeds. This function 96 returns `boost::none` if all buffers representing the body have 97 been returned in previous calls or if it sets `ec` to indicate an 98 error. Otherwise, if there are buffers remaining the function 99 should return a pair with the first element containing a non-zero 100 length buffer sequence representing the next set of octets in 101 the body, while the second element is a `bool` meaning `true` 102 if there may be additional buffers returned on a subsequent call, 103 or `false` if the buffer returned on this call is the last 104 buffer representing the body. 105 The function will ensure that `!ec` is `true` if there was 106 no error or set to the appropriate error code if there was one. 107 ] 108]] 109 110[heading Exemplar] 111 112[concept_BodyWriter] 113 114[heading Models] 115 116* [link beast.ref.boost__beast__http__basic_dynamic_body.writer `basic_dynamic_body::writer`] 117* [link beast.ref.boost__beast__http__basic_file_body__writer `basic_file_body::writer`] 118* [link beast.ref.boost__beast__http__basic_string_body.writer `basic_string_body::writer`] 119* [link beast.ref.boost__beast__http__buffer_body.writer `buffer_body::writer`] 120* [link beast.ref.boost__beast__http__empty_body.writer `empty_body::writer`] 121* [link beast.ref.boost__beast__http__span_body.writer `span_body::writer`] 122* [link beast.ref.boost__beast__http__vector_body.writer `vector_body::writer`] 123 124[endsect] 125