forked from boostorg/beast
107 lines
3.1 KiB
Plaintext
107 lines
3.1 KiB
Plaintext
[/
|
|
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:serializer_streams Serializer Stream Operations]
|
|
|
|
Algorithms for sending entire messages to streams are intended for light
|
|
duty use-cases such as simple clients and low utilization servers.
|
|
Sophisticated algorithms will need to do more:
|
|
|
|
* Send the message header first.
|
|
|
|
* Send a message incrementally: bounded work in each I/O cycle.
|
|
|
|
* Use a custom chunk decorator or allocator when sending messages.
|
|
|
|
* Use a series of caller-provided buffers to represent the body.
|
|
|
|
All of these operations require callers to manage the lifetime of state
|
|
information associated with the operation, by constructing a __serializer__
|
|
object with the message to be sent. The serializer type has this declaration:
|
|
```
|
|
template<
|
|
bool isRequest,
|
|
class Body,
|
|
class Fields,
|
|
class ChunkDecorator = no_chunk_decorator,
|
|
class Allocator = std::allocator<char>
|
|
>
|
|
class serializer;
|
|
```
|
|
|
|
The choices for template types must match the message passed on construction.
|
|
This code creates an HTTP response and the corresponding serializer:
|
|
```
|
|
response<string_body> res;
|
|
...
|
|
serializer<false, string_body, fields> sr{res};
|
|
```
|
|
The convenience function
|
|
[link beast.ref.http__make_serializer `make_serializer`]
|
|
is provided to avoid repetition of template argument types. The declaration
|
|
for `sr` in the code above may be written as:
|
|
```
|
|
...
|
|
auto sr = make_serializer(res);
|
|
```
|
|
|
|
The stream operations which work on serializers are:
|
|
|
|
[table Serializer Stream Operations
|
|
[[Name][Description]]
|
|
[[
|
|
[link beast.ref.http__write.overload1 [*write]]
|
|
][
|
|
Send everything in a __serializer__ to a __SyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.http__async_write.overload1 [*async_write]]
|
|
][
|
|
Send everything in a __serializer__ asynchronously to an __AsyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.http__write_header.overload1 [*write_header]]
|
|
][
|
|
Send only the header from a __serializer__ to a __SyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.http__async_write_header [*async_write_header]]
|
|
][
|
|
Send only the header from a __serializer__ asynchronously to an __AsyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.http__write_some.overload1 [*write_some]]
|
|
][
|
|
Send some __serializer__ buffer data to a __SyncWriteStream__.
|
|
]]
|
|
[[
|
|
[link beast.ref.http__async_write_some [*async_write_some]]
|
|
][
|
|
Send some __serializer__ buffer data asynchronously to an __AsyncWriteStream__.
|
|
]]
|
|
]
|
|
|
|
Here is an example of using a serializer to send a message on a stream
|
|
synchronously. This performs the same operation as calling `write(stream, m)`:
|
|
|
|
```
|
|
template<class SyncWriteStream, bool isRequest, class Body, class Fields>
|
|
void send(SyncWriteStream& stream, message<isRequest, Body, Fields> const& m)
|
|
{
|
|
static_assert(is_sync_write_stream<SyncWriteStream>::value,
|
|
"SyncWriteStream requirements not met");
|
|
serializer<isRequest, Body, Fields> sr{m};
|
|
do
|
|
{
|
|
write_some(stream, sr);
|
|
}
|
|
while(! sr.is_done());
|
|
}
|
|
```
|
|
|
|
[endsect]
|