boostorg/beast
1
0
Fork 1
mirror of https://github.com/boostorg/beast.git synced 2025-07-30 12:57:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Improve documentation of websocket::stream::async_close

Browse Source 
Addresses #2730
This commit is contained in:
Mohammad Nejati
2025-02-10 18:59:22 +00:00
committed by Mohammad Nejati
parent 684fbfb356
commit 8c3d8a907d
2 changed files with 41 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
include/boost/beast/websocket/impl/close.hpp
View File

@ -178,7 +178,6 @@ public:
} }
// Read until a receiving a close frame // Read until a receiving a close frame
// TODO There should be a timeout on this
if(impl.rd_remain > 0) if(impl.rd_remain > 0)
goto read_payload; goto read_payload;
for(;;) for(;;)

78
include/boost/beast/websocket/stream.hpp
View File

@ -1574,27 +1574,27 @@ public:
// //
//-------------------------------------------------------------------------- //--------------------------------------------------------------------------
/** Send a websocket close control frame. /** Perform the WebSocket closing handshake and close the underlying stream.
This function is used to send a This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>, <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
which begins the websocket closing handshake. The session ends when to begin the WebSocket closing handshake and waits for a corresponding
both ends of the connection have sent and received a close frame. close frame in response. Once received, it calls @ref teardown
to gracefully shut down the underlying stream.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. However, it can still read
incoming message data. A read returning @ref error::closed indicates a
successful connection closure.
The call blocks until one of the following conditions is true: The call blocks until one of the following conditions is true:
@li The close frame is written. @li The closing handshake completes, and @ref teardown finishes.
@li An error occurs. @li An error occurs.
The algorithm, known as a <em>composed operation</em>, is implemented The algorithm, known as a <em>composed operation</em>, is implemented
in terms of calls to the next layer's `write_some` function. in terms of calls to the next layer's `write_some` function.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. Instead, the program should
continue reading message data until an error occurs. A read returning
@ref error::closed indicates a successful connection closure.
@param cr The reason for the close. @param cr The reason for the close.
If the close reason specifies a close code other than If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is @ref beast::websocket::close_code::none, the close frame is
@ -1609,27 +1609,27 @@ public:
void void
close(close_reason const& cr); close(close_reason const& cr);
/** Send a websocket close control frame. /** Perform the WebSocket closing handshake and close the underlying stream.
This function is used to send a This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>, <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
which begins the websocket closing handshake. The session ends when to begin the WebSocket closing handshake and waits for a corresponding
both ends of the connection have sent and received a close frame. close frame in response. Once received, it calls @ref teardown
to gracefully shut down the underlying stream.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. However, it can still read
incoming message data. A read returning @ref error::closed indicates a
successful connection closure.
The call blocks until one of the following conditions is true: The call blocks until one of the following conditions is true:
@li The close frame is written. @li The closing handshake completes, and @ref teardown finishes.
@li An error occurs. @li An error occurs.
The algorithm, known as a <em>composed operation</em>, is implemented The algorithm, known as a <em>composed operation</em>, is implemented
in terms of calls to the next layer's `write_some` function. in terms of calls to the next layer's `write_some` function.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. Instead, the program should
continue reading message data until an error occurs. A read returning
@ref error::closed indicates a successful connection closure.
@param cr The reason for the close. @param cr The reason for the close.
If the close reason specifies a close code other than If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is @ref beast::websocket::close_code::none, the close frame is
@ -1644,30 +1644,34 @@ public:
void void
close(close_reason const& cr, error_code& ec); close(close_reason const& cr, error_code& ec);
/** Send a websocket close control frame asynchronously. /** Perform the WebSocket closing handshake asynchronously and close
the underlying stream.
This function is used to asynchronously send a This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>, <a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
which begins the websocket closing handshake. The session ends when to begin the WebSocket closing handshake and waits for a corresponding
both ends of the connection have sent and received a close frame. close frame in response. Once received, it calls @ref async_teardown
to gracefully shut down the underlying stream asynchronously.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. However, it can still read
incoming message data. A read returning @ref error::closed indicates a
successful connection closure.
This call always returns immediately. The asynchronous operation This call always returns immediately. The asynchronous operation
will continue until one of the following conditions is true: will continue until one of the following conditions is true:
@li The close frame finishes sending. @li The closing handshake completes, and @ref async_teardown finishes.
@li An error occurs. @li An error occurs.
If a timeout occurs, @ref close_socket will be called to close the
underlying stream.
The algorithm, known as a <em>composed asynchronous operation</em>, The algorithm, known as a <em>composed asynchronous operation</em>,
is implemented in terms of calls to the next layer's `async_write_some` is implemented in terms of calls to the next layer's `async_write_some`
function. No other operations except for message reading operations function. No other operations except for message reading operations
should be initiated on the stream after a close operation is started. should be initiated on the stream after a close operation is started.
After beginning the closing handshake, the program should not write
further message data, pings, or pongs. Instead, the program should
continue reading message data until an error occurs. A read returning
@ref error::closed indicates a successful connection closure.
@param cr The reason for the close. @param cr The reason for the close.
If the close reason specifies a close code other than If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is @ref beast::websocket::close_code::none, the close frame is
@ -1704,7 +1708,7 @@ public:
`terminal` cancellation succeeds when supported by the underlying stream. `terminal` cancellation succeeds when supported by the underlying stream.
@note `terminal` cancellation will may close the underlying socket. @note `terminal` cancellation may close the underlying socket.
@see @see
@li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a> @li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>