Serializer Stream Operations

Non-trivial algorithms need to do more than send entire messages at once, such as:

Send the header first, and the body later.
Send a message incrementally: bounded work in each I/O cycle.
Use a series of caller-provided buffers to represent the body.

These tasks may be performed by using the serializer stream interfaces. To use these interfaces, first construct an appropriate serializer from the message to be sent:

Table 1.15. Serializer

Name	Description
`serializer`	/// Provides buffer oriented HTTP message serialization functionality. template< bool isRequest, class Body, class Fields = fields > class serializer;
`request_serializer`	/// A serializer for HTTP/1 requests template< class Body, class Fields = fields > using request_serializer = serializer<true, Body, Fields>;
`response_serializer`	/// A serializer for HTTP/1 responses template< class Body, class Fields = fields > using response_serializer = serializer<false, Body, Fields>;

Name

Description

serializer

/// Provides buffer oriented HTTP message serialization functionality.
template<
    bool isRequest,
    class Body,
    class Fields = fields
>
class serializer;

request_serializer

/// A serializer for HTTP/1 requests
template<
    class Body,
    class Fields = fields
>
using request_serializer = serializer<true, Body, Fields>;

response_serializer

/// A serializer for HTTP/1 responses
template<
    class Body,
    class Fields = fields
>
using response_serializer = serializer<false, Body, Fields>;

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;

response_serializer<string_body> sr{res};

The stream operations which work on serializers are:

Table 1.16. Serializer Stream Operations

Name	Description
write	Send everything in a `serializer` to a SyncWriteStream.
async_write	Send everything in a `serializer` asynchronously to an AsyncWriteStream.
write_header	Send only the header from a `serializer` to a SyncWriteStream.
async_write_header	Send only the header from a `serializer` asynchronously to an AsyncWriteStream.
write_some	Send part of a `serializer` to a SyncWriteStream.
async_write_some	Send part of a `serializer` 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):

/** Send a message to a stream synchronously.

    @param stream The stream to write to. This type must support
    the @b SyncWriteStream concept.

    @param m The message to send. The Body type must support
    the @b BodyWriter concept.
*/
template<
    class SyncWriteStream,
    bool isRequest, class Body, class Fields>
void
send(
    SyncWriteStream& stream,
    message<isRequest, Body, Fields> const& m)
{
    // Check the template types
    static_assert(is_sync_write_stream<SyncWriteStream>::value,
        "SyncWriteStream requirements not met");
    static_assert(is_body_writer<Body>::value,
        "BodyWriter requirements not met");

    // Create the instance of serializer for the message
    serializer<isRequest, Body, Fields> sr{m};

    // Loop until the serializer is finished
    do
    {
        // This call guarantees it will make some
        // forward progress, or otherwise return an error.
        write_some(stream, sr);
    }
    while(! sr.is_done());
}

Boost C++ Libraries

Serializer Stream Operations