forked from boostorg/beast
ff15cf8688
New buffer sequence classes are provided to allow full
control over the serialization of chunk-encoded message
payloads:
* chunk_header
A ConstBufferSequence representing the chunk header.
It includes a hexadecimal-encoded size, an optional
set of chunk extensions, and the trailing CRLF
required to denote the end of the chunk header.
This allows the caller to manually serialize the chunk
body in one or more calls to a stream output function.
The caller must also output an object of type `chunk_crlf`
to the stream to indicate the end of the chunk body.
* chunk_crlf
A small ConstBufferSequence that simply represents
the two character sequence "\r\n" (CRLF). This is needed
for the case where the caller wants to output a chunk
body as a series of buffers (i.e. "chunking a chunk").
* chunk_body
A ConstBufferSequence representing a complete chunk.
This includes the size, an optional set of chunk extensions,
a caller provided buffer containing the body, and the
required CRLF that follows.
* chunk_final
A ConstBufferSequence representing a final chunk. It
includes an optional set of caller-provided field trailers
* chunk_extensions
A container for building a set of chunk extensions to use
during serialization. The use of the container is optional,
callers may provide their own buffer containing a correctly
formatted set of chunk extensions, or they may use their
own convenience container which meets the requirements.
The basic_fields container is modified to allow construction
outside the context of a message. The container can be used
to provide trailers to `chunk_final`.
Actions Required:
* Remove references to ChunkDecorators. Use the new chunk-encoding
buffer sequences to manually produce a chunked payload body in
the case where control over the chunk-extensions and/or trailers
is required.
56 lines
2.2 KiB
Plaintext
56 lines
2.2 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 Notes]
|
|
|
|
Because calls to read data may return a variable amount of bytes, the
|
|
interface to calls that read data require an object that meets the requirements
|
|
of __DynamicBuffer__. This concept is modeled on __streambuf__.
|
|
|
|
The implementation does not perform queueing or buffering of messages. If
|
|
desired, these features should be provided by callers. The impact of this
|
|
design is that library users are in full control of the allocation strategy
|
|
used to store data and the back-pressure applied on the read and write side
|
|
of the underlying TCP/IP connection.
|
|
|
|
[heading Asynchronous Operations]
|
|
|
|
Asynchronous versions are available for all functions:
|
|
|
|
[ws_snippet_20]
|
|
|
|
Calls to asynchronous initiation functions support the extensible asynchronous
|
|
model developed by the Boost.Asio author, allowing for traditional completion
|
|
handlers, stackful or stackless coroutines, and even futures:
|
|
|
|
[ws_snippet_21]
|
|
|
|
[heading The io_service]
|
|
|
|
The creation and operation of the __io_service__ associated with the
|
|
underlying stream is left to the callers, permitting any implementation
|
|
strategy including one that does not require threads for environments
|
|
where threads are unavailable. Beast WebSocket itself does not use
|
|
or require threads.
|
|
|
|
[heading Thread Safety]
|
|
|
|
Like a regular __Asio__ socket, a
|
|
[link beast.ref.beast__websocket__stream `stream`]
|
|
is not thread safe. Callers are responsible for synchronizing operations on
|
|
the socket using an implicit or explicit strand, as per the Asio documentation.
|
|
The asynchronous interface supports one active read and one active write
|
|
simultaneously. Undefined behavior results if two or more reads or two or
|
|
more writes are attempted concurrently. Caller initiated WebSocket ping, pong,
|
|
and close operations each count as an active write.
|
|
|
|
The implementation uses composed asynchronous operations internally; a high
|
|
level read can cause both reads and writes to take place on the underlying
|
|
stream. This behavior is transparent to callers.
|
|
|
|
[endsect]
|