Merge pull request #235 from boostorg/develop

Develop to master

Author: mzimbres

README.md

@@ -4,41 +4,39 @@ Boost.Redis is a high-level [Redis](https://redis.io/) client library built on t
 [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:
+The requirements for using Boost.Redis are
 
-* Boost. The library is included in Boost distributions starting with 1.84.
+* Boost 1.84 or higher.
 * C++17 or higher.
 * Redis 6 or higher (must support RESP3).
-* Gcc (11, 12), Clang (11, 13, 14) and Visual Studio (16 2019, 17 2022).
+* GCC (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
+To use the library it is necessary to include
 
 ```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
+in no more than one source file in your applications. To build the
+examples and tests with cmake run
 
 ```cpp
 # Linux
-$ BOOST_ROOT=/opt/boost_1_84_0 cmake --preset g++-11
+$ BOOST_ROOT=/opt/boost_1_84_0 cmake -S <source-dir> -B <binary-dir>
 
 # Windows 
 $ cmake -G "Visual Studio 17 2022" -A x64 -B bin64 -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
 ```
 
+For more details see https://github.com/boostorg/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
+The code below uses a short-lived connection to
+[ping](https://redis.io/commands/ping/) the Redis server 
 
 ```cpp
 auto co_main(config const& cfg) -> net::awaitable<void>
@@ -50,11 +48,11 @@ auto co_main(config const& cfg) -> net::awaitable<void>
    request req;
    req.push("PING", "Hello world");
 
-   // Response where the PONG response will be stored.
+   // Response object.
    response<std::string> resp;
 
    // Executes the request.
-   co_await conn->async_exec(req, resp, net::deferred);
+   co_await conn->async_exec(req, resp);
    conn->cancel();
 
    std::cout << "PING: " << std::get<0>(resp).value() << std::endl;
@@ -98,7 +96,7 @@ receiver(std::shared_ptr<connection> conn) -> net::awaitable<void>
    while (conn->will_reconnect()) {
 
       // Reconnect to channels.
-      co_await conn->async_exec(req, ignore, net::deferred);
+      co_await conn->async_exec(req, ignore);
 
       // Loop reading Redis pushes.
       for (;;) {
@@ -145,21 +143,18 @@ req.push_range("SUBSCRIBE", std::cbegin(list), std::cend(list));
 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.
+Sending a request to Redis is performed with `boost::redis::connection::async_exec` as already stated.  The
+`boost::redis::request::config` object inside the request dictates how
+the `boost::redis::connection` the request is handled in some
+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 uses the following strategy to deal with Redis responses
 
-* `boost::redis::request` is used for requests whose number of commands are not dynamic.
-* **Dynamic**: Otherwise use `boost::redis::generic_response`.
+* `boost::redis::request` used for requests whose number of commands are not dynamic.
+* `boost::redis::generic_response` used when the size is dynamic.
 
 For example, the request below has three commands
 
@@ -170,8 +165,8 @@ req.push("INCR", "key");
 req.push("QUIT");
 ```
 
-and its response also has three comamnds and can be read in the
-following response object
+and therefore its response will also contain three elements which can
+be read in the following reponse object
 
 ```cpp
 response<std::string, int, std::string>
@@ -186,7 +181,7 @@ To ignore responses to individual commands in the request use the tag
 
 ```cpp
 // Ignore the second and last responses.
-response<std::string, boost::redis::ignore_t, std::string, boost::redis::ignore_t>
+response<std::string, ignore_t, std::string, ignore_t>
 ```
 
 The following table provides the resp3-types returned by some Redis
@@ -230,7 +225,7 @@ req.push("QUIT");
 
 ```
 
-can be read in the tuple below
+can be read in the response object below
 
 ```cpp
 response<
@@ -243,17 +238,18 @@ response<
 > resp;
 ```
 
-Where both are passed to `async_exec` as showed elsewhere
+Then, to execute the request and read the response use `async_exec` as
+shown below
 
 ```cpp
-co_await conn->async_exec(req, resp, net::deferred);
+co_await conn->async_exec(req, resp);
 ```
 
 If the intention is to ignore responses altogether use `ignore`
 
 ```cpp
 // Ignores the response
-co_await conn->async_exec(req, ignore, net::deferred);
+co_await conn->async_exec(req, ignore);
 ```
 
 Responses that contain nested aggregates or heterogeneous data
@@ -279,27 +275,23 @@ req.push("SUBSCRIBE", "channel");
 req.push("QUIT");
 ```
 
-must be read in this tuple `response<std::string, std::string>`,
-that has static size two.
+must be read in the response object `response<std::string, std::string>`.
 
 ### Null
 
-It is not uncommon for apps to access keys that do not exist or
-that have already expired in the Redis server, to deal with these
-cases Boost.Redis provides support for `std::optional`. To use it,
-wrap your type around `std::optional` like this
+It is not uncommon for apps to access keys that do not exist or that
+have already expired in the Redis server, to deal with these usecases
+wrap the type with an `std::optional` as shown below
 
 ```cpp
 response<
    std::optional<A>,
    std::optional<B>,
    ...
    > resp;
-
-co_await conn->async_exec(req, resp, net::deferred);
 ```
 
-Everything else stays pretty much the same.
+Everything else stays the same.
 
 ### Transactions
 
@@ -321,22 +313,18 @@ use the following response type
 ```cpp
 using boost::redis::ignore;
 
-using exec_resp_type = 
+
+response<
+   ignore_t,  // multi
+   ignore_t,  // QUEUED
+   ignore_t,  // QUEUED
+   ignore_t,  // QUEUED
    response<
       std::optional<std::string>, // get
       std::optional<std::vector<std::string>>, // lrange
       std::optional<std::map<std::string, std::string>> // hgetall
-   >;
-
-response<
-   boost::redis::ignore_t,  // multi
-   boost::redis::ignore_t,  // get
-   boost::redis::ignore_t,  // lrange
-   boost::redis::ignore_t,  // hgetall
-   exec_resp_type,        // exec
+   > // exec
 > resp;
-
-co_await conn->async_exec(req, resp, net::deferred);
 ```
 
 For a complete example see cpp20_containers.cpp.
@@ -350,7 +338,7 @@ commands won't fit in the model presented above, some examples are
 
 * Commands (like `set`) whose responses don't have a fixed
   RESP3 type. Expecting an `int` and receiving a blob-string
-  will result in error.
+  results in an error.
 * RESP3 aggregates that contain nested aggregates can't be read in STL containers.
 * Transactions with a dynamic number of commands can't be read in a `response`.
 
@@ -384,7 +372,7 @@ using other types
 ```cpp
 // Receives any RESP3 simple or aggregate data type.
 boost::redis::generic_response resp;
-co_await conn->async_exec(req, resp, net::deferred);
+co_await conn->async_exec(req, resp);
 ```
 
 For example, suppose we want to retrieve a hash data structure
@@ -411,7 +399,7 @@ the following customization points
 void boost_redis_to_bulk(std::string& to, mystruct const& obj);
 
 // Deserialize
-void boost_redis_from_bulk(mystruct& obj, char const* p, std::size_t size, boost::system::error_code& ec)
+void boost_redis_from_bulk(mystruct& u, node_view const& node, boost::system::error_code&)
 ```
 
 These functions are accessed over ADL and therefore they must be
@@ -447,7 +435,7 @@ main motivations for choosing an echo server are
 
    * Simple to implement and does not require expertise level in most languages.
    * I/O bound: Echo servers have very low CPU consumption in general
-     and  therefore are excelent to  measure how a program handles concurrent requests.
+     and  therefore are excellent to  measure how a program handles concurrent requests.
    * It simulates very well a typical backend in regard to concurrency.
 
 I also imposed some constraints on the implementations
@@ -510,7 +498,7 @@ in the graph, the reasons are
      I don't know for sure why it is so slow, I suppose it has
      something to do with its lack of automatic
      [pipelining](https://redis.io/docs/manual/pipelining/) support.
-     In fact, the more TCP connections I lauch the worse its
+     In fact, the more TCP connections I launch the worse its
      performance gets.
 
    * Libuv: I left it out because it would require me writing to much
@@ -676,6 +664,28 @@ https://lists.boost.org/Archives/boost/2023/01/253944.php.
 
 ## Changelog
 
+### Boost 1.88
+
+* (Issue [233](https://github.com/boostorg/redis/issues/233))
+  To deal with keys that might not exits in the Redis server, the
+  library supports `std::optional`, for example
+  `response<std::optional<std::vector<std::string>>>`. In some cases
+  however, such as the [MGET](https://redis.io/docs/latest/commands/mget/) command,
+  each element in the vector might be non exiting, now it is possible
+  to specify a response as `response<std::optional<std::vector<std::optional<std::string>>>>`.
+
+* (Issue [225](https://github.com/boostorg/redis/issues/225))
+  Use `deferred` as the connection default completion token.
+
+* (Issue [128](https://github.com/boostorg/redis/issues/128))
+  Adds a new `async_exec` overload that allows passing response
+  adapters. This makes it possible to receive Redis responses directly
+  in custom data structures thereby avoiding uncessary data copying.
+  Thanks to Ruben Perez (@anarthal) for implementing this feature.
+
+* There are also other multiple small improvements in this release,
+  users can refer to the git history for more details.
+
 ### Boost 1.87
 
 * (Issue [205](https://github.com/boostorg/redis/issues/205))
@@ -721,11 +731,11 @@ https://lists.boost.org/Archives/boost/2023/01/253944.php.
   makes it simpler to use the `requirepass` configuration in Redis.
 
 * (Issue [189](https://github.com/boostorg/redis/issues/189)).
-  Fixes narrowing convertion by using `std::size_t` instead of
+  Fixes narrowing conversion by using `std::size_t` instead of
   `std::uint64_t` for the sizes of bulks and aggregates. The code
   relies now on `std::from_chars` returning an error if a value
   greater than 32 is received on platforms on which the size
-  of`std::size_t` is 32.
+  of `std::size_t` is 32.
 
 
 ### Boost 1.84 (First release in Boost)
@@ -797,7 +807,7 @@ https://lists.boost.org/Archives/boost/2023/01/253944.php.
   would wait for a response to arrive before sending the next one. Now requests
   are continuously coalesced and written to the socket. `request::coalesce`
   became unnecessary and was removed. I could measure significative performance
-  gains with theses changes.
+  gains with these changes.
 
 * Improves serialization examples using Boost.Describe to serialize to JSON and protobuf. See
   cpp20_json.cpp and cpp20_protobuf.cpp for more details.
@@ -1004,7 +1014,7 @@ https://lists.boost.org/Archives/boost/2023/01/253944.php.
 * Fixes a bug in the `connection::async_run(host, port)` overload
   that was causing crashes on reconnection.
 
-* Fixes the executor usage in the connection class. Before theses
+* Fixes the executor usage in the connection class. Before these
   changes it was imposing `any_io_executor` on users.
 
 * `connection::async_receiver_event` is not cancelled anymore when

example/cpp20_chat_room.cpp

@@ -5,7 +5,6 @@
  */
 
 #include <boost/redis/connection.hpp>
-#include <boost/asio/deferred.hpp>
 #include <boost/asio/signal_set.hpp>
 #include <boost/asio/co_spawn.hpp>
 #include <boost/asio/detached.hpp>
@@ -18,13 +17,12 @@
 #if defined(BOOST_ASIO_HAS_POSIX_STREAM_DESCRIPTOR)
 
 namespace asio = boost::asio;
-using stream_descriptor = asio::deferred_t::as_default_on_t<asio::posix::stream_descriptor>;
-using signal_set = asio::deferred_t::as_default_on_t<asio::signal_set>;
+using asio::posix::stream_descriptor;
+using asio::signal_set;
 using boost::asio::async_read_until;
 using boost::asio::awaitable;
 using boost::asio::co_spawn;
 using boost::asio::consign;
-using boost::asio::deferred;
 using boost::asio::detached;
 using boost::asio::dynamic_buffer;
 using boost::asio::redirect_error;
@@ -52,7 +50,7 @@ receiver(std::shared_ptr<connection> conn) -> awaitable<void>
    while (conn->will_reconnect()) {
 
       // Subscribe to channels.
-      co_await conn->async_exec(req, ignore, deferred);
+      co_await conn->async_exec(req, ignore);
 
       // Loop reading Redis push messages.
       for (error_code ec;;) {
@@ -76,7 +74,7 @@ auto publisher(std::shared_ptr<stream_descriptor> in, std::shared_ptr<connection
       auto n = co_await async_read_until(*in, dynamic_buffer(msg, 1024), "\n");
       request req;
       req.push("PUBLISH", "channel", msg);
-      co_await conn->async_exec(req, ignore, deferred);
+      co_await conn->async_exec(req, ignore);
       msg.erase(0, n);
    }
 }