boost-1-85-0-b1-rc1

# Boost.Redis Boost.Redis is a high-level [Redis](https://redis.io/) client library built on top of [Boost.Asio](https://www.boost.org/doc/libs/release/doc/html/boost_asio.html) that implements the Redis protocol [RESP3](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md). The requirements for using Boost.Redis are: * Boost. The library is included in Boost distributions starting with 1.84. * C++17 or higher. * Redis 6 or higher (must support RESP3). * Gcc (10, 11, 12), Clang (11, 13, 14) and Visual Studio (16 2019, 17 2022). * Have basic-level knowledge about [Redis](https://redis.io/docs/) and [Boost.Asio](https://www.boost.org/doc/libs/1_82_0/doc/html/boost_asio/overview.html). The latest release can be downloaded on https://github.com/boostorg/redis/releases. The library headers can be found in the `include` subdirectory and a compilation of the source ```cpp #include <boost/redis/src.hpp> ``` is required. The simplest way to do it is to included this header in no more than one source file in your applications. To build the examples and tests cmake is supported, for example ```cpp # Linux $ BOOST_ROOT=/opt/boost_1_84_0 cmake --preset g++-11 # Windows $ cmake -G "Visual Studio 17 2022" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake ``` <a name="connection"></a> ## Connection Let us start with a simple application that uses a short-lived connection to send a [ping](https://redis.io/commands/ping/) command to Redis ```cpp auto co_main(config const& cfg) -> net::awaitable<void> { auto conn = std::make_shared<connection>(co_await net::this_coro::executor); conn->async_run(cfg, {}, net::consign(net::detached, conn)); // A request containing only a ping command. request req; req.push("PING", "Hello world"); // Response where the PONG response will be stored. response<std::string> resp; // Executes the request. co_await conn->async_exec(req, resp, net::deferred); conn->cancel(); std::cout << "PING: " << std::get<0>(resp).value() << std::endl; } ``` The roles played by the `async_run` and `async_exec` functions are * `async_exec`: Execute the commands contained in the request and store the individual responses in the `resp` object. Can be called from multiple places in your code concurrently. * `async_run`: Resolve, connect, ssl-handshake, resp3-handshake, health-checks, reconnection and coordinate low-level read and write operations (among other things). ### Server pushes Redis servers can also send a variety of pushes to the client, some of them are * [Pubsub](https://redis.io/docs/manual/pubsub/) * [Keyspace notification](https://redis.io/docs/manual/keyspace-notifications/) * [Client-side caching](https://redis.io/docs/manual/client-side-caching/) The connection class supports server pushes by means of the `boost::redis::connection::async_receive` function, which can be called in the same connection that is being used to execute commands. The coroutine below shows how to used it ```cpp auto receiver(std::shared_ptr<connection> conn) -> net::awaitable<void> { request req; req.push("SUBSCRIBE", "channel"); generic_response resp; conn->set_receive_response(resp); // Loop while reconnection is enabled while (conn->will_reconnect()) { // Reconnect to channels. co_await conn->async_exec(req, ignore, net::deferred); // Loop reading Redis pushes. for (;;) { error_code ec; co_await conn->async_receive(resp, net::redirect_error(net::use_awaitable, ec)); if (ec) break; // Connection lost, break so we can reconnect to channels. // Use the response resp in some way and then clear it. ... consume_one(resp); } } } ``` <a name="requests"></a> ## Requests Redis requests are composed of one or more commands (in the Redis documentation they are called [pipelines](https://redis.io/topics/pipelining)). For example ```cpp // Some example containers. std::list<std::string> list {...}; std::map<std::string, mystruct> map { ...}; // The request can contain multiple commands. request req; // Command with variable length of arguments. req.push("SET", "key", "some value", "EX", "2"); // Pushes a list. req.push_range("SUBSCRIBE", list); // Same as above but as an iterator range. req.push_range("SUBSCRIBE", std::cbegin(list), std::cend(list)); // Pushes a map. req.push_range("HSET", "key", map); ``` Sending a request to Redis is performed with `boost::redis::connection::async_exec` as already stated. ### Config flags The `boost::redis::request::config` object inside the request dictates how the `boost::redis::connection` should handle the request in some important situations. The reader is advised to read it carefully. <a name="responses"></a> ## Responses Boost.Redis uses the following strategy to support Redis responses * `boost::redis::request` is used for requests whose number of commands are not dynamic. * **Dynamic**: Otherwise use `boost::redis::generic_response`. For example, the request below has three commands ```cpp request req; req.push("PING"); req.push("INCR", "key"); req.push("QUIT"); ``` and its response also has three comamnds and can be read in the following response object ```cpp response<std::string, int, std::string> ``` The response behaves as a tuple and must have as many elements as the request has commands (exceptions below). It is also necessary that each tuple element is capable of storing the response to the command it refers to, otherwise an error will occur. To ignore responses to individual commands in the request use the tag `boost::redis::ignore_t`, for example ```cpp // Ignore the second and last responses. response<std::string, boost::redis::ignore_t, std::string, boost::redis::ignore_t> ``` The following table provides the resp3-types returned by some Redis commands Command | RESP3 type | Documentation ---------|-------------------------------------|-------------- lpush | Number | https://redis.io/commands/lpush lrange | Array | https://redis.io/commands/lrange set | Simple-string, null or blob-string | https://redis.io/commands/set get | Blob-string | https://redis.io/commands/get smembers | Set | https://redis.io/commands/smembers hgetall | Map | https://redis.io/commands/hgetall To map these RESP3 types into a C++ data structure use the table below RESP3 type | Possible C++ type | Type ---------------|--------------------------------------------------------------|------------------ Simple-string | `std::string` | Simple Simple-error | `std::string` | Simple Blob-string | `std::string`, `std::vector` | Simple Blob-error | `std::string`, `std::vector` | Simple Number | `long long`, `int`, `std::size_t`, `std::string` | Simple Double | `double`, `std::string` | Simple Null | `std::optional<T>` | Simple Array | `std::vector`, `std::list`, `std::array`, `std::deque` | Aggregate Map | `std::vector`, `std::map`, `std::unordered_map` | Aggregate Set | `std::vector`, `std::set`, `std::unordered_set` | Aggregate Push | `std::vector`, `std::map`, `std::unordered_map` | Aggregate For example, the