[/
    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:

[http_snippet_9]

The choices for template types must match the message passed on construction.
This code creates an HTTP response and the corresponding serializer:

[http_snippet_10]

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:

[http_snippet_11]

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)`:

[http_snippet_12]

[endsect]