Many improvements in the examples.

Author: mzimbres

CMakeLists.txt

@@ -43,7 +43,7 @@ write_basic_package_version_file(
     COMPATIBILITY AnyNewerVersion
 )
 
-find_package(Boost 1.79 REQUIRED)
+find_package(Boost 1.80 REQUIRED)
 include_directories(${Boost_INCLUDE_DIRS})
 
 find_package(OpenSSL REQUIRED)
@@ -54,19 +54,25 @@ include_directories(include)
 # Main function for the examples.
 #=======================================================================
 
-add_library(common STATIC examples/common.cpp)
+add_library(common STATIC
+   examples/common/common.cpp
+   examples/common/main.cpp
+   examples/common/aedis.cpp
+)
 target_compile_features(common PUBLIC cxx_std_20)
 
 # Executables
 #=======================================================================
 
-#add_executable(intro_sync examples/intro_sync.cpp) // Uncomment after update to Boost 1.80
-
 add_executable(intro examples/intro.cpp)
 target_link_libraries(intro common)
 target_compile_features(intro PUBLIC cxx_std_20)
 add_test(intro intro)
 
+add_executable(intro_sync examples/intro_sync.cpp)
+target_compile_features(intro_sync PUBLIC cxx_std_20)
+add_test(intro_sync intro_sync)
+
 add_executable(chat_room examples/chat_room.cpp)
 target_compile_features(chat_room PUBLIC cxx_std_20)
 target_link_libraries(chat_room common)

README.md

@@ -16,15 +16,21 @@ Some of its distinctive features are
 * Back pressure, cancellation and low latency.
 
 In addition to that, Aedis hides most of the low-level Asio code away
-from the user. For example, the coroutine below retrieves Redis hashes
+from the user, which in the majority of the case will be concerned
+with three library entities
+
+* `aedis::resp3::request`: A container of Redis commands.
+* `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)
 
 ```cpp
 auto hgetall(std::shared_ptr<connection> conn) -> net::awaitable<void>
 {
    // 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,11 +45,10 @@ auto hgetall(std::shared_ptr<connection> conn) -> net::awaitable<void>
 }
 ```
 
-The execution of `connection::async_exec` as shown above is
-triggered by the `connection::async_run` member function, which is
-required to be running concurrently for as long as the connection
-stands.  For example, the code below uses a short-lived connection to
-execute the coroutine above
+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()
@@ -53,7 +58,7 @@ net::awaitable<void> async_main()
    // Resolves and connects (from examples/common.hpp to avoid vebosity)
    co_await connect(conn, "127.0.0.1", "6379");
 
-   // Runs and executes the request.
+   // Runs hgetall (previous example).
    co_await (conn->async_run() || hgetall(conn));
 }
 ```
@@ -67,32 +72,25 @@ reading from the socket. The reationale behind this design is
 * Support server pushes and requests in the same connection object,
   concurrently.
 
-In the following sections we will discuss with more details the main
-code entities Aedis users are concerned with, namely
-
-* `aedis::resp3::request`: A container of Redis commands.
-* `aedis::adapt()`: A function that adapts data structures to receive Redis responses.
-* `aedis::connection`: A connection to the Redis server.
-
-before that however, users might find it helpful to skim over the
-examples, to gain a better feeling about the library capabilities.
+Before we see with more detail how connections, requests and responses
+work, users might find it helpful to skim over the examples, to gain a
+better feeling about the library capabilities.
 
 * intro.cpp: The Aedis hello-world program. Sends one command to Redis 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.
 * 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.
 * subscriber.cpp: Shows how to implement pubsub with reconnection re-subscription.
 * echo_server.cpp: A simple TCP echo server.
 * chat_room.cpp: A command line chat built on Redis pubsub.
-
-The next two examples uses the Aedis low-level API
-
-* low_level_sync.cpp: Sends a ping synchronously.
-* low_level_async.cpp: Sends a ping asynchronously
+* 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
-grouped in common.hpp.
+grouped in common.hpp. The main function is defined in main.cpp and
+used by all examples.
 
 <a name="requests"></a>
 ### Requests
@@ -498,7 +496,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.
-Another common scenarios for reconnection is, for example, a failover
+Another common scenario for reconnection is, for example, a failover
 with sentinels, covered in `resolve_with_sentinel.cpp` example.
 
 #### Execute
@@ -613,7 +611,7 @@ co_await (conn.async_exec(...) || time.async_wait(...))
   should last.
 * The cancellation will be ignored if the request has already
   been written to the socket.
-* It is usually a better idea to have a healthy checker that adding
+* It is usually a better idea to have a healthy checker than adding
   per request timeout, see subscriber.cpp for an example.
 
 ```cpp

examples/chat_room.cpp

@@ -10,7 +10,7 @@
 #include <aedis.hpp>
 #include <unistd.h>
 
-#include "common.hpp"
+#include "common/common.hpp"
 
 namespace net = boost::asio;
 using namespace net::experimental::awaitable_operators;
@@ -55,7 +55,7 @@ auto subscriber(std::shared_ptr<connection> conn) -> net::awaitable<void>
    co_await conn->async_exec(req);
 }
 
-// Called from the main function (see common.cpp)
+// Called from the main function (see main.cpp)
 auto async_main() -> net::awaitable<void>
 {
    auto ex = co_await net::this_coro::executor;

examples/common/aedis.cpp

@@ -0,0 +1,8 @@
+/* Copyright (c) 2018-2022 Marcelo Zimbres Silva ([email protected])
+ *
+ * Distributed under the Boost Software License, Version 1.0. (See
+ * accompanying file LICENSE.txt)
+ */
+
+#include <aedis.hpp>
+#include <aedis/src.hpp>

examples/common.cpp renamed to examples/common/common.cpp

@@ -6,6 +6,7 @@
 
 #include "common.hpp"
 
+#include <boost/asio.hpp>
 #if defined(BOOST_ASIO_HAS_CO_AWAIT)
 #include <boost/asio/experimental/awaitable_operators.hpp>
 #include <iostream>
@@ -18,9 +19,6 @@ using aedis::resp3::request;
 using aedis::adapt;
 using aedis::operation;
 
-// Include this in no more than one .cpp file.
-#include <aedis/src.hpp>
-
 namespace
 {
 auto redir(boost::system::error_code& ec)
@@ -74,21 +72,4 @@ connect(
       throw std::runtime_error("Connect timeout");
 }
 
-extern net::awaitable<void> async_main();
-
-// Main function used in our examples.
-auto main() -> int
-{
-   try {
-      net::io_context ioc;
-      net::co_spawn(ioc, async_main(), net::detached);
-      ioc.run();
-   } catch (std::exception const& e) {
-      std::cerr << "Error: " << e.what() << std::endl;
-      return 1;
-   }
-}
-
-#else // defined(BOOST_ASIO_HAS_CO_AWAIT)
-auto main() -> int {std::cout << "Requires coroutine support." << std::endl; return 0;}
 #endif // defined(BOOST_ASIO_HAS_CO_AWAIT)

examples/common.hpp renamed to examples/common/common.hpp

@@ -0,0 +1,29 @@
+/* Copyright (c) 2018-2022 Marcelo Zimbres Silva ([email protected])
+ *
+ * Distributed under the Boost Software License, Version 1.0. (See
+ * accompanying file LICENSE.txt)
+ */
+
+#include <iostream>
+#include <boost/asio.hpp>
+#if defined(BOOST_ASIO_HAS_CO_AWAIT)
+
+namespace net = boost::asio;
+extern net::awaitable<void> async_main();
+
+// The main function used in our examples.
+auto main() -> int
+{
+   try {
+      net::io_context ioc;
+      net::co_spawn(ioc, async_main(), net::detached);
+      ioc.run();
+   } catch (std::exception const& e) {
+      std::cerr << "Error: " << e.what() << std::endl;
+      return 1;
+   }
+}
+
+#else // defined(BOOST_ASIO_HAS_CO_AWAIT)
+auto main() -> int {std::cout << "Requires coroutine support." << std::endl; return 0;}
+#endif // defined(BOOST_ASIO_HAS_CO_AWAIT)

examples/common/main.cpp

@@ -11,7 +11,7 @@
 #include <map>
 #include <vector>
 
-#include "common.hpp"
+#include "common/common.hpp"
 
 namespace net = boost::asio;
 using namespace net::experimental::awaitable_operators;
@@ -92,7 +92,7 @@ auto transaction(std::shared_ptr<connection> conn) -> net::awaitable<void>
    print(std::get<1>(std::get<4>(resp)).value());
 }
 
-// Called from the main function (see common.cpp)
+// Called from the main function (see main.cpp)
 net::awaitable<void> async_main()
 {
    auto conn = std::make_shared<connection>(co_await net::this_coro::executor);

examples/containers.cpp

@@ -8,7 +8,7 @@
 #if defined(BOOST_ASIO_HAS_CO_AWAIT)
 #include <boost/asio/experimental/awaitable_operators.hpp>
 #include <aedis.hpp>
-#include "common.hpp"
+#include "common/common.hpp"
 
 namespace net = boost::asio;
 using namespace net::experimental::awaitable_operators;
@@ -44,7 +44,7 @@ auto listener(std::shared_ptr<connection> conn) -> net::awaitable<void>
       net::co_spawn(ex, echo_server_session(co_await acc.async_accept(), conn), net::detached);
 }
 
-// Called from the main function (see common.cpp)
+// Called from the main function (see main.cpp)
 auto async_main() -> net::awaitable<void>
 {
    auto ex = co_await net::this_coro::executor;

examples/echo_server.cpp

@@ -8,15 +8,15 @@
 #if defined(BOOST_ASIO_HAS_CO_AWAIT)
 #include <boost/asio/experimental/awaitable_operators.hpp>
 #include <aedis.hpp>
-#include "common.hpp"
+#include "common/common.hpp"
 
 namespace net = boost::asio;
 using namespace net::experimental::awaitable_operators;
 using aedis::adapt;
 using aedis::resp3::request;
 
-// Called from the main function (see common.cpp)
-net::awaitable<void> async_main()
+// Called from the main function (see main.cpp)
+auto async_main() -> net::awaitable<void>
 {
    request req;
    req.get_config().cancel_on_connection_lost = true;