forked from boostorg/beast
Documentation work
This commit is contained in:
1 parent
d4ec693a61
commit
9d5d4d56a4
46 files changed
+1264
-153
No files matched your search
@@ -0,0 +1,55 @@
|
||||
[/
|
||||
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 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.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]
|
||||
Reference in new issue
Block a user