ceph/src/Beast/doc/types/Writer.qbk

   1 [/
   2     Copyright (c) 2013-2017 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
   8 [section:Writer Writer requirements]
   9
  10 A `Writer` serializes the message body. The implementation creates an instance
  11 of this type when serializing a message, and calls into it zero or more times
  12 to provide buffers containing the data. The interface of `Writer` is intended
  13 to allow serialization in these scenarios:
  14
  15 * A body that does not entirely fit in memory.
  16 * A body produced incrementally from coroutine output.
  17 * A body represented by zero or more buffers already in memory.
  18 * A body as a series of buffers when the content size is not known ahead of time.
  19 * Body data generated on demand from other threads.
  20 * Body data computed algorithmically.
  21
  22 In this table:
  23
  24 * `X`  denotes a type meeting the requirements of `Writer`.
  25
  26 * `a`  denotes a value of type `X`.
  27
  28 * `m`  denotes a value of type `message const&` where
  29         `std::is_same<decltype(m.body), Body::value_type>:value == true`.
  30
  31 * `ec` is a value of type [link beast.ref.error_code `error_code&`]
  32
  33 * `wf` is a [*write function]: a function object of unspecified type provided
  34        by the implementation which accepts any value meeting the requirements
  35        of __ConstBufferSequence__ as its single parameter.
  36
  37 [table Writer requirements
  38 [[operation] [type] [semantics, pre/post-conditions]]
  39 [
  40     [`X a(m);`]
  41     []
  42     [
  43         `a` is constructible from `m`. The lifetime of `m` is guaranteed
  44         to end no earlier than after `a` is destroyed. This function must
  45         be `noexcept`.
  46     ]
  47 ]
  48 [
  49     [`a.init(ec)`]
  50     [`void`]
  51     [
  52         Called immediately after construction. If the function sets an
  53         error code in `ec`, the serialization is aborted and the error
  54         is propagated to the caller. This function must be `noexcept`.
  55     ]
  56 ]
  57 [
  58     [`a.content_length()`]
  59     [`std::uint64_t`]
  60     [
  61         If this member is present, it is called after initialization
  62         and before calls to provide buffers. The serialized message will
  63         have the Content-Length field set to the value returned from
  64         this function. If this member is absent, the serialized message
  65         body will be chunk-encoded for HTTP versions 1.1 and later, else
  66         the serialized message body will be sent unmodified, with the
  67         error `boost::asio::error::eof` returned to the caller, to notify
  68         they should close the connection to indicate the end of the message.
  69         This function must be `noexcept`.
  70     ]
  71 ]
  72 [
  73     [`a.write(ec, wf)`]
  74     [`bool`]
  75     [
  76         Called repeatedly after `init` succeeds. `wf` is a function object
  77         which takes as its single parameter any value meeting the requirements
  78         of __ConstBufferSequence__. Buffers provided to this write function
  79         must remain valid until the next member function of `writer` is
  80         invoked (which may be the destructor). This function returns `true`
  81         to indicate all message body data has been written, or `false` if
  82         there is more body data.
  83     ]
  84 ]
  85 ]
  86
  87 [note
  88     Definitions for required `Writer` member functions should be declared
  89     inline so the generated code can become part of the implementation.
  90 ]
  91
  92 Exemplar:
  93 ```
  94 struct writer
  95 {
  96 public:
  97     /** Construct the writer.
  98
  99         The msg object is guaranteed to exist for the lifetime of the writer.
 100
 101         Exceptions:
 102             No-throw guarantee.
 103
 104         @param msg The message whose body is to be written.
 105     */
 106     template<bool isRequest, class Body, class Headers>
 107     explicit
 108     writer(message<isRequest, Body, Headers> const& msg) noexcept;
 109
 110     /** Initialize the writer.
 111
 112         Called once immediately after construction.
 113         The writer can perform initialization which may fail.
 114
 115         @param ec Contains the error code if any errors occur.
 116     */
 117     void
 118     init(error_code& ec) noexcept;
 119
 120     /** Returns the content length.
 121
 122         If this member is present, the implementation will set the
 123         Content-Length field accordingly. If absent, the implementation will
 124         use chunk-encoding or terminate the connection to indicate the end
 125         of the message.
 126     */
 127     std::uint64_t
 128     content_length() noexcept;
 129
 130     /** Write zero or one buffer representing the message body.
 131
 132         Postconditions:
 133
 134             If return value is `true`:
 135                 * Callee made zero or one calls to `write`.
 136                 * There is no more data remaining to write.
 137
 138             If return value is `false`:
 139                 * Callee does not take ownership of resume.
 140                 * Callee made one call to `write`.
 141
 142         @param ec Set to indicate an error. This will cause an
 143         asynchronous write operation to complete with the error.
 144
 145         @param write A functor the writer will call to provide the next
 146         set of buffers. Ownership of the buffers is not transferred,
 147         the writer must guarantee that the buffers remain valid until the
 148         next member function is invoked, which may be the destructor.
 149
 150         @return `true` if there is no more data to send,
 151                 `false` when there may be more data.
 152     */
 153     template<class WriteFunction>
 154     bool
 155     write(
 156         error_code&,
 157         WriteFunction&& wf) noexcept;
 158 };
 159 ```
 160
 161 [endsect]