Doc improvements and add guarded_op class.

Author: mzimbres

README.md

@@ -23,14 +23,21 @@ with three library entities
 * `aedis::adapt()`: A function that adapts data structures to receive Redis responses.
 * `aedis::connection`: A connection to the Redis server.
 
-For example, the coroutine below reads Redis [hashes](https://redis.io/docs/data-types/hashes/)
-in a `std::map` and quits the connection (see containers.cpp)
+For example, the coroutine below uses a short-lived connection to read Redis
+[hashes](https://redis.io/docs/data-types/hashes/)
+in a `std::map` (see containers.cpp)
 
 ```cpp
-auto hgetall(std::shared_ptr<connection> conn) -> net::awaitable<void>
+auto hgetall() -> net::awaitable<void>
 {
+   auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
+
+   // Resolves and connects (from examples/common.hpp to avoid vebosity)
+   co_await connect(conn, "127.0.0.1", "6379");
+
    // A request contains multiple Redis commands.
    request req;
+   req.get_config().cancel_on_connection_lost = true;
    req.push("HELLO", 3);
    req.push("HGETALL", "hset-key");
    req.push("QUIT");
@@ -39,46 +46,29 @@ auto hgetall(std::shared_ptr<connection> conn) -> net::awaitable<void>
    std::tuple<aedis::ignore, std::map<std::string, std::string>, aedis::ignore> resp;
 
    // Executes the request and reads the response.
-   co_await conn->async_exec(req, adapt(resp));
-
-   // Uses the map ...
-}
-```
+   co_await (conn->async_run() || conn->async_exec(req, adapt(resp)));
 
-The execution of `connection::async_exec` as shown above must
-still be triggered by the `connection::async_run` member function. For
-example, the code below uses a short-lived connection to execute the
-coroutine above
-
-```cpp
-net::awaitable<void> async_main()
-{
-   auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
-
-   // Resolves and connects (from examples/common.hpp to avoid vebosity)
-   co_await connect(conn, "127.0.0.1", "6379");
-
-   // Runs hgetall (previous example).
-   co_await (conn->async_run() || hgetall(conn));
+   // Use the map ...
 }
 ```
 
-Long-lived connections follow the same principle (see the examples
-below) and will be discussed in more detail later.  The role of the
-`async_run` is to coordinate IO and ensure the connection is always
-reading from the socket. The reationale behind this design is
+The execution of `connection::async_exec` as shown above is triggered
+by the `connection::async_run` member function, whose role is to
+coordinate IO and ensure the connection is always reading from the
+socket. The rationale behind this design is
 
 * Provide quick reaction to disconnections and hence faster failovers.
 * Support server pushes and requests in the same connection object,
   concurrently.
 
-Before we see with more detail how connections, requests and responses
-work, users might find it useful to skim over the examples in order to
-gain a better feeling about the library capabilities.
+Long-lived connections follow the same principle and will be discussed
+more later. Before we go to the next sections, users might find it
+useful to skim over the examples in order to gain a better feeling
+about the library capabilities.
 
 * intro.cpp: The Aedis hello-world program. Sends one command and quits the connection.
 * intro_tls.cpp: Same as intro.cpp but over TLS.
-* intro_sync.cpp: Shows how to use the conneciton class synchronously.
+* intro_sync.cpp: Shows how to use the connection class synchronously.
 * containers.cpp: Shows how to send and receive STL containers and how to use transactions.
 * serialization.cpp: Shows how to serialize types using Boost.Json.
 * resolve_with_sentinel.cpp: Shows how to resolve a master address using sentinels.
@@ -88,14 +78,14 @@ gain a better feeling about the library capabilities.
 * low_level_sync.cpp: Sends a ping synchronously using the low-level API.
 * low_level_async.cpp: Sends a ping asynchronously using the low-level API.
 
-To avoid repetition code that is common to all examples have been
+To avoid repetition code that is common to all examples has been
 grouped in common.hpp. The main function used in some async examples
 has been factored out in the main.cpp file.
 
 <a name="requests"></a>
-### Requests
+## Requests
 
-Redis requests are composed of one or more Redis commands (in
+Redis requests are composed of one or more commands (in the
 Redis documentation they are called
 [pipelines](https://redis.io/topics/pipelining)). For example
 
@@ -152,11 +142,11 @@ std::map<std::string, mystruct> map {...};
 req.push_range("HSET", "key", map);
 ```
 
-Example serialization.cpp shows how store json string in Redis.
+Example serialization.cpp shows how store json strings in Redis.
 
 <a name="responses"></a>
 
-### Responses
+## Responses
 
 Aedis uses the following strategy to support Redis responses
 
@@ -182,7 +172,7 @@ std::tuple<std::string, int, std::string>
 The pattern might have become apparent to the reader: the tuple 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 ocurr.
+response to the command it refers to, otherwise an error will occur.
 To ignore responses to individual commands in the request use the tag
 `aedis::ignore`
 
@@ -425,7 +415,7 @@ containers. The same reasoning also applies to sets e.g. `SMEMBERS`
 and other data structures in general.
 
 <a name="connection"></a>
-### Connection
+## Connection
 
 The `aedis::connection` is a class that provides async-only
 communication with a Redis server by means of three member
@@ -452,7 +442,7 @@ the points above with more detail.
 
 #### Run
 
-The code snipet in the overview section has shown us an example that
+The code snippet in the overview section has shown us an example that
 used `connection::async_run` in short-lived connection, in the general
 case however, applications will connect to a Redis server and hang
 around for as long as possible, until the connection is lost for some
@@ -495,7 +485,7 @@ auto async_main() -> net::awaitable<void>
 
 It is important to emphasize that Redis servers use the old
 communication protocol RESP2 by default, therefore it is necessary to
-send a `HELLO 3` command everytime a connection is established.
+send a `HELLO 3` command every time a connection is established.
 Another common scenario for reconnection is, for example, a failover
 with sentinels, covered in `resolve_with_sentinel.cpp` example.
 
@@ -624,12 +614,12 @@ co_await (conn.async_run(...) || time.async_wait(...))
 co_await (conn.async_exec(...) || conn.async_exec(...) || ... || conn.async_exec(...))
 ```
 
-* This works but is considered an antipattern. Unless
+* This works but is considered an anti-pattern. Unless
   the user has set `aedis::resp3::request::config::coalesce` to
   `false`, and he shouldn't, the connection will automatically merge
   the individual requests into a single payload anyway.
 
-## Why Aedis
+## Comparison
 
 The main reason for why I started writing Aedis was to have a client
 compatible with the Asio asynchronous model. As I made progresses I could
@@ -642,6 +632,8 @@ stars, namely
 
 * https://github.com/sewenew/redis-plus-plus
 
+### Aedis vs Redis-plus-plus
+
 Before we start it is important to mentioning some of the things
 redis-plus-plus does not support
 
@@ -738,7 +730,7 @@ enqueueing a message and triggering a write when it can be sent.
 It is also not clear how are pipelines realised with this design
 (if at all).
 
-### Echo server benchmark
+## Echo server benchmark
 
 This document benchmarks the performance of TCP echo servers I
 implemented in different languages using different Redis clients.  The
@@ -860,8 +852,9 @@ The requirements for using Aedis are
 
 The following compilers are supported
 
-- Tested with gcc: 10, 11, 12.
-- Tested with clang: 11, 13, 14.
+- Gcc: 10, 11, 12.
+- Clang: 11, 13, 14.
+- Visual Studio 17 2022, Visual Studio 16 2019.
 
 ## Acknowledgement
 
@@ -875,18 +868,19 @@ Acknowledgement to people that helped shape Aedis
 
 ## Changelog
 
-### master
+### 1.4.0
 
 * Removes dependency on Boost.Hana.
 * Removes dependency on `boost::string_view`, now using `std::string_view`.
+* Fixes build and setup CI on windows.
 
 ### v1.3.0-1
 
 * Upgrades to Boost 1.80.0
 
 * Removes automatic sending of the `HELLO` command. This can't be
   implemented properly without bloating the connection class. It is
-  now a user responsability to send HELLO. Requests that contain it have
+  now a user responsibility to send HELLO. Requests that contain it have
   priority over other requests and will be moved to the front of the
   queue, see `aedis::resp3::request::config` 
 
@@ -999,7 +993,7 @@ Acknowledgement to people that helped shape Aedis
   is possible in simple reconnection strategies but bloats the class
   in more complex scenarios, for example, with sentinel,
   authentication and TLS. This is trivial to implement in a separate
-  coroutine. As a result the enum `event` and `async_receive_event`
+  coroutine. As a result the `enum event` and `async_receive_event`
   have been removed from the class too.
 
 * Fixes a bug in `connection::async_receive_push` that prevented

examples/containers.cpp

@@ -50,18 +50,25 @@ auto store(std::shared_ptr<connection> conn) -> net::awaitable<void>
 }
 
 // Retrieves a Redis hash as an std::map.
-auto hgetall(std::shared_ptr<connection> conn) -> net::awaitable<void>
+auto hgetall() -> net::awaitable<void>
 {
+   auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
+
+   // Resolves and connects (from examples/common.hpp to avoid vebosity)
+   co_await connect(conn, "127.0.0.1", "6379");
+
+   // A request contains multiple Redis commands.
    request req;
    req.get_config().cancel_on_connection_lost = true;
    req.push("HELLO", 3);
    req.push("HGETALL", "hset-key");
    req.push("QUIT");
 
+   // Tuple elements will hold the response to each command in the request.
    std::tuple<aedis::ignore, std::map<std::string, std::string>, aedis::ignore> resp;
 
-   co_await conn->async_exec(req, adapt(resp));
-
+   // Executes the request and reads the response.
+   co_await (conn->async_run() || conn->async_exec(req, adapt(resp)));
    print(std::get<1>(resp));
 }
 
@@ -102,9 +109,9 @@ net::awaitable<void> async_main()
    co_await connect(conn, "127.0.0.1", "6379");
    co_await (conn->async_run() || store(conn));
 
-   co_await connect(conn, "127.0.0.1", "6379");
-   co_await (conn->async_run() || hgetall(conn));
+   co_await hgetall();
 
+   // Resused the connection object.
    co_await connect(conn, "127.0.0.1", "6379");
    co_await (conn->async_run() || transaction(conn));
 }

include/aedis/connection.hpp

@@ -18,9 +18,8 @@ namespace aedis {
 /** @brief A connection to the Redis server.
  *  @ingroup high-level-api
  *
- *  This class keeps a healthy connection to the Redis instance where
- *  commands can be sent at any time. For more details, please see the
- *  documentation of each individual function.
+ *  For more details, please see the documentation of each individual
+ *  function.
  *
  *  @tparam AsyncReadWriteStream A stream that supports reading and
  *  writing.
@@ -98,9 +97,9 @@ class basic_connection :
     *  void f(boost::system::error_code);
     *  @endcode
     *
-    *  This function will complete when the connection is lost as
-    *  follows. If the error is boost::asio::error::eof this function
-    *  will complete without error.
+    *  This function will complete when the connection is lost. If the
+    *  error is boost::asio::error::eof this function will complete
+    *  without error.
     */
    template <class CompletionToken = boost::asio::default_completion_token_t<executor_type>>
    auto async_run(CompletionToken token = CompletionToken{})
@@ -110,7 +109,7 @@ class basic_connection :
 
    /** @brief Executes a command on the Redis server asynchronously.
     *
-    *  This function will send a request to the Redis server and
+    *  This function sends a request to the Redis server and
     *  complete after the response has been processed. If the request
     *  contains only commands that don't expect a response, the
     *  completion occurs after it has been written to the underlying
@@ -146,7 +145,7 @@ class basic_connection :
     *
     *  Users that expect server pushes should call this function in a
     *  loop. If a push arrives and there is no reader, the connection
-    *  will hang and eventually timeout.
+    *  will hang.
     *
     *  @param adapter The response adapter.
     *  @param token The Asio completion token.
@@ -193,7 +192,6 @@ class basic_connection :
    template <class, class> friend class detail::connection_base;
    template <class, class> friend struct detail::exec_read_op;
    template <class, class> friend struct detail::exec_op;
-   template <class, class> friend struct detail::receive_op;
    template <class> friend struct detail::reader_op;
    template <class> friend struct detail::writer_op;
    template <class> friend struct detail::run_op;

include/aedis/detail/connection_base.hpp

@@ -19,6 +19,7 @@
 #include <boost/asio/ip/tcp.hpp>
 #include <boost/asio/steady_timer.hpp>
 #include <boost/asio/bind_executor.hpp>
+#include <boost/asio/deferred.hpp>
 #include <boost/asio/experimental/channel.hpp>
 
 #include <aedis/adapt.hpp>
@@ -47,7 +48,7 @@ class connection_base {
    connection_base(executor_type ex, std::pmr::memory_resource* resource)
    : writer_timer_{ex}
    , read_timer_{ex}
-   , push_channel_{ex}
+   , guarded_op_{ex}
    , read_buffer_{resource}
    , write_buffer_{resource}
    , reqs_{resource}
@@ -76,7 +77,7 @@ class connection_base {
          }
          case operation::receive:
          {
-            push_channel_.cancel();
+            guarded_op_.cancel();
             return 1U;
          }
          default: BOOST_ASSERT(false); return 0;
@@ -154,10 +155,10 @@ class connection_base {
       CompletionToken token = CompletionToken{})
    {
       auto f = detail::make_adapter_wrapper(adapter);
-      return boost::asio::async_compose
-         < CompletionToken
-         , void(boost::system::error_code, std::size_t)
-         >(detail::receive_op<Derived, decltype(f)>{&derived(), f}, token, writer_timer_);
+
+      return guarded_op_.async_wait(
+         resp3::async_read(derived().next_layer(), make_dynamic_buffer(adapter.get_max_read_size(0)), f, boost::asio::deferred),
+         std::move(token));
    }
 
    template <class CompletionToken>
@@ -276,7 +277,6 @@ class connection_base {
 
    using reqs_type = std::pmr::deque<std::shared_ptr<req_info>>;
 
-   template <class, class> friend struct detail::receive_op;
    template <class> friend struct detail::reader_op;
    template <class> friend struct detail::writer_op;
    template <class> friend struct detail::run_op;
@@ -371,7 +371,7 @@ class connection_base {
    // IO objects
    timer_type writer_timer_;
    timer_type read_timer_;
-   push_channel_type push_channel_;
+   detail::guarded_operation<executor_type> guarded_op_;
 
    std::pmr::string read_buffer_;
    std::pmr::string write_buffer_;