Skip to content

Improve documentation of websocket::stream::async_close #2981

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 11, 2025
Merged

Improve documentation of websocket::stream::async_close #2981

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3df161a
Increase timeout tolerance in ping tests
ashtum Feb 10, 2025
7f4a11e
Improve documentation of websocket::stream::async_close
ashtum Feb 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion include/boost/beast/websocket/impl/close.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,7 +178,6 @@ class stream<NextLayer, deflateSupported>::close_op
}

// Read until a receiving a close frame
// TODO There should be a timeout on this
if(impl.rd_remain > 0)
goto read_payload;
for(;;)
Expand Down
78 changes: 41 additions & 37 deletions include/boost/beast/websocket/stream.hpp
View file
Open in desktop
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,34 @@ 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.

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>,
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 Expand Up @@ -1704,7 +1708,7 @@ class 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
@li <a href="https://tools.ietf.org/html/rfc6455#section-7.1.2">Websocket Closing Handshake (RFC6455)</a>
Expand Down
8 changes: 4 additions & 4 deletions test/beast/websocket/ping.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ class ping_test : public websocket_test_suite
test::connect(ws1.next_layer(), ws2.next_layer());
ws1.set_option(stream_base::timeout{
stream_base::none(),
std::chrono::milliseconds(500),
std::chrono::seconds(1),
false
});
ws2.async_accept(test::success_handler());
Expand All @@ -125,13 +125,13 @@ class ping_test : public websocket_test_suite
system_error{ec});
got_timeout = true;
});
ioc.run_for(std::chrono::milliseconds(250));
ioc.run_for(std::chrono::milliseconds(500));
ioc.restart();
ws2.async_ping("", test::success_handler());
ioc.run_for(std::chrono::milliseconds(300));
ioc.run_for(std::chrono::milliseconds(600));
ioc.restart();
BEAST_EXPECT(!got_timeout);
ioc.run_for(std::chrono::milliseconds(500));
ioc.run_for(std::chrono::seconds(1));
ioc.restart();
BEAST_EXPECT(got_timeout);
}
Expand Down
Loading