Skip to content

Commit

Permalink
Improve documentation of websocket::stream::async_close
Browse files Browse the repository at this point in the history 
Addresses #2730
  • Loading branch information
@ashtum
ashtum committed Feb 10, 2025
1 parent 95386da commit 561a1ff
Showing 1 changed file with 37 additions and 36 deletions.
73 changes: 37 additions & 36 deletions include/boost/beast/websocket/stream.hpp
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1574,27 +1574,27 @@ class stream
//
//--------------------------------------------------------------------------

/** Send a websocket close control frame.
/** Perform the WebSocket closing handshake and close the underlying stream.
This function is used to send 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
both ends of the connection have sent and received a close frame.
This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
to begin the WebSocket closing handshake and waits for a corresponding
close frame in response. Once received, it calls @ref teardown
to gracefully shut down the underlying stream.
The call blocks until one of the following conditions is true:
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.
@li The close frame is written.
The call blocks until one of the following conditions is true:
@li The closing handshake completes, and @ref teardown finishes.
@li An error occurs.
The algorithm, known as a <em>composed operation</em>, is implemented
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.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
Expand All @@ -1609,27 +1609,27 @@ class stream
void
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
<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
both ends of the connection have sent and received a close frame.
This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
to begin the WebSocket closing handshake and waits for a corresponding
close frame in response. Once received, it calls @ref teardown
to gracefully shut down the underlying stream.
The call blocks until one of the following conditions is true:
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.
@li The close frame is written.
The call blocks until one of the following conditions is true:
@li The closing handshake completes, and @ref teardown finishes.
@li An error occurs.
The algorithm, known as a <em>composed operation</em>, is implemented
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.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
Expand All @@ -1644,30 +1644,31 @@ class stream
void
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
<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
both ends of the connection have sent and received a close frame.
This function sends a
<a href="https://tools.ietf.org/html/rfc6455#section-5.5.1">close frame</a>
to begin the WebSocket closing handshake and waits for a corresponding
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
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.
The algorithm, known as a <em>composed asynchronous operation</em>,
is implemented in terms of calls to the next layer's `async_write_some`
function. No other operations except for message reading operations
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.
If the close reason specifies a close code other than
@ref beast::websocket::close_code::none, the close frame is
Expand Down

0 comments on commit 561a1ff

Please sign in to comment.