boost::redis::co_connection::receive

Wait for server pushes.

Synopsis

Declared in <boost/redis/co_connection.hpp>

capy::io_task
receive();

Description

This function suspends until at least one server push is received by the connection. On completion, an unspecified number of pushes will have been added to the response object set with set_receive_response. Use the functions in the response object to know how many messages were received and consume them.

To prevent receiving an unbounded number of pushes, the connection blocks further read operations on the socket when its internal receive buffer fills up. When that happens, in‐flight exec calls and health checks won't make any progress and the connection may eventually time out. To avoid this, applications that expect server pushes should call this function continuously in a loop.

This function does not remove messages from the response object passed to set_receive_response. Use the functions in the response object to achieve this.

Only a single instance of receive may be outstanding for a given connection at any time. Launching a second receive fails with error::already_running.

receive does not complete when reconnection happens or when run completes.

To avoid deadlocks, the task calling receive should not also call exec in a way where they can block each other. That is, avoid the following pattern:

capy::task<void> receiver(co_connection& conn)
{
   // Do NOT do this!!! The receive buffer might get full while
   // exec runs, which will block all read operations until receive
   // is called. The two operations end up waiting for each other,
   // making the connection unresponsive. If you need this pattern,
   // use two connections instead.
   co_await conn.receive();
   co_await conn.exec(req, resp);
}

For an example see corosio_subscriber.cpp.

Awaiting the returned task yields a capy::io_result containing a single std::error_code:

auto [ec] = co_await conn.receive();

Cancellation

The usual capy cancellation semantics apply. The operation can be used in constructs like capy::timeout and capy::with_any.

Return Value

A task that yields a capy::io_result holding the operation's std::error_code on completion.

Created with MrDocs