diff --git a/include/boost/beast/websocket/impl/close.hpp b/include/boost/beast/websocket/impl/close.hpp index 0e6549d6..623e87bb 100644 --- a/include/boost/beast/websocket/impl/close.hpp +++ b/include/boost/beast/websocket/impl/close.hpp @@ -178,7 +178,6 @@ public: } // Read until a receiving a close frame - // TODO There should be a timeout on this if(impl.rd_remain > 0) goto read_payload; for(;;) diff --git a/include/boost/beast/websocket/stream.hpp b/include/boost/beast/websocket/stream.hpp index 7dd307d7..f307c572 100644 --- a/include/boost/beast/websocket/stream.hpp +++ b/include/boost/beast/websocket/stream.hpp @@ -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 - close frame, - 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 + close frame + 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. + + 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: - @li The close frame is written. - + @li The closing handshake completes, and @ref teardown finishes. @li An error occurs. The algorithm, known as a composed operation, 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 @@ -1609,27 +1609,27 @@ public: 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 - close frame, - 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 + close frame + 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. + + 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: - @li The close frame is written. - + @li The closing handshake completes, and @ref teardown finishes. @li An error occurs. The algorithm, known as a composed operation, 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 @@ -1644,30 +1644,34 @@ public: 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 - close frame, - 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 + close frame + 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. + If a timeout occurs, @ref close_socket will be called to close the + underlying stream. + The algorithm, known as a composed asynchronous operation, 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 @@ -1704,7 +1708,7 @@ public: `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 @li Websocket Closing Handshake (RFC6455)