From c7b6e2eeb6fff3be75f732a6c83d3dc5a1036370 Mon Sep 17 00:00:00 2001 From: Marcelo Zimbres Date: Sat, 8 Jan 2022 02:35:08 +0100 Subject: [PATCH] More improvements in the docs. --- examples/nested_response.cpp | 5 +- examples/response_queue.cpp | 10 +--- examples/subscriber.cpp | 2 +- include/aedis/aedis.hpp | 47 +++++++++++------ include/aedis/command.hpp | 4 ++ include/aedis/resp3/adapter/error.hpp | 7 ++- include/aedis/resp3/node.hpp | 3 ++ include/aedis/resp3/serializer.hpp | 72 +++++++++++---------------- 8 files changed, 75 insertions(+), 75 deletions(-) diff --git a/examples/nested_response.cpp b/examples/nested_response.cpp index f483bb2d..0c72d0e7 100644 --- a/examples/nested_response.cpp +++ b/examples/nested_response.cpp @@ -20,8 +20,7 @@ namespace net = aedis::net; using net::async_write; using net::buffer; -/* Shows how to read nested responses. -*/ +/// Shows how to read nested responses. net::awaitable nested_response() { @@ -44,7 +43,7 @@ net::awaitable nested_response() co_await async_read(socket, buffer, adapt(ping)); co_await async_read(socket, buffer); - // Print the responses. + // Prints the responses. std::cout << "hello: "; for (auto const& e: hello) std::cout << e << " "; std::cout << "\nPing: " << ping; diff --git a/examples/response_queue.cpp b/examples/response_queue.cpp index 8c3404b3..fd705f5f 100644 --- a/examples/response_queue.cpp +++ b/examples/response_queue.cpp @@ -20,15 +20,7 @@ namespace net = aedis::net; using net::async_write; using net::buffer; -/* Processes the responses in a loop using the helper queue. - - In most cases commands will be added dynamically to the request for - example as users interact with the code. In order to process the - responses asynchronously users have to keep a queue of the expected - commands or use the one provided by the serializer class. - - The example below shows how to do it. - */ +/// Processes the responses in a loop using the helper queue. net::awaitable ping() { try { diff --git a/examples/subscriber.cpp b/examples/subscriber.cpp index 0034511e..da9ded82 100644 --- a/examples/subscriber.cpp +++ b/examples/subscriber.cpp @@ -26,7 +26,7 @@ using net::buffer; indefinitely. Notice we store the id of the connection (attributed by the redis - server) to be able to identify it (in logs for example). + server) to be able to identify it (in the logs for example). After starting the example you can test it by sending messages with the redis-client like this diff --git a/include/aedis/aedis.hpp b/include/aedis/aedis.hpp index c4b045ff..7bcd6f60 100644 --- a/include/aedis/aedis.hpp +++ b/include/aedis/aedis.hpp @@ -35,12 +35,14 @@ // Pages /** \page examples Examples - - \b Basics + * + \b Basics: Focuses on small code snipets that show basic usage of + the library. - intro.cpp - Illustrates the basic usage. + Users should start here. Some commands are sent to the Redis + server and the responses are printed to screen. - key_expiration.cpp @@ -49,8 +51,9 @@ - nested_response.cpp - When the data-structure returned by Redis cannot be translated - in a C++ built-in type like STL containers, std::string, etc. + Shows how to read responses to commands that cannot be + translated in a C++ built-in type like std::string or STL + containers. - subscriber.cpp @@ -58,40 +61,52 @@ - response_queue.cpp - Shows how to process responses asynchronously. + In most cases commands will be added dynamically to the request + for example as users interact with app. In order to process the + responses asynchronously users have to keep a queue of the + expected commands or use the one provided by the serializer + class. This example shows how to do it. - \b STL \b Containers: Many of the Redis data structures can be directly translated in to STL containers. The example bellow shows how to do that. The list of Redis data types can be found at https://redis.io/topics/data-types. + \b STL \b Containers: Many of the Redis data structures can be + directly translated in to STL containers. The examples bellow show + how to do that. The list of Redis data types can be found at + https://redis.io/topics/data-types. - hashes.cpp - Shows how to read Redis hashes in a \c std::map, \c std::unordered_map and \c std::vector. + Shows how to read Redis hashes in a \c std::map, \c + std::unordered_map and \c std::vector. - lists.cpp - Shows how to read Redis lists in \c std::list, \c std::deque, \c std::vector. It also illustrates basic serialization. + Shows how to read Redis lists in \c std::list, + \c std::deque, \c std::vector. It also illustrates basic serialization. - sets.cpp - Shows how to read Redis sets in a \c std::set, \c std::unordered_set and \c std::vector. + Shows how to read Redis sets in a \c std::set, \c std::unordered_set + and \c std::vector. \b Customization \b points - serialization.cpp - Shows how to de/serialize your own (simple) data-structures. + Shows how to de/serialize your own non-aggregate data-structures. - response_adapter.cpp Customization point for users that want to de/serialize their - own containers. + own data-structures. - \b Adavanced: The main difference the examples bellow and the + \b Adavanced: The main difference the examples below and the others above is that they user long lasting connections to Redis. This is the desired way to communicate with redis. - echo_server.cpp - Shows the basic principles behind async communication with a database in a tcp server. In this case, the server is a proxy between the user and the database. + Shows the basic principles behind async communication with a + database in a tcp server. In this case, the server is a proxy + between the user and the database. */ /** \page reference Reference @@ -128,10 +143,10 @@ /** \defgroup read_write_ops Free functions (read/write operations) - * \brief alkjd ajs + * \brief RESP3 read and write functions. */ /** \defgroup operators Operators - * \brief alkjd ajs + * \brief Operators defined in Aedis */ diff --git a/include/aedis/command.hpp b/include/aedis/command.hpp index ae8bb0f6..03f17ca2 100644 --- a/include/aedis/command.hpp +++ b/include/aedis/command.hpp @@ -13,6 +13,10 @@ namespace aedis { /** \brief Redis commands. * \ingroup enums + * + * For a full list of commands see https://redis.io/commands. The + * list of commands below are read from Redis with the \c command + * command */ enum class command { /// https://redis.io/commands/acl diff --git a/include/aedis/resp3/adapter/error.hpp b/include/aedis/resp3/adapter/error.hpp index 8bff1add..20770f36 100644 --- a/include/aedis/resp3/adapter/error.hpp +++ b/include/aedis/resp3/adapter/error.hpp @@ -6,7 +6,7 @@ namespace aedis { namespace resp3 { namespace adapter { -/** \brief Errors that may occurr while processing a response. +/** \brief Errors that may occurr whe deserializing a response. * \ingroup enums */ enum class error @@ -21,7 +21,10 @@ enum class error simple_error, /// Got RESP3 blob_error. - blob_error + blob_error, + + /// Got RESP3 null but the response type does not support it. + null, }; namespace detail { diff --git a/include/aedis/resp3/node.hpp b/include/aedis/resp3/node.hpp index 9081c4ed..4c9caa36 100644 --- a/include/aedis/resp3/node.hpp +++ b/include/aedis/resp3/node.hpp @@ -17,6 +17,9 @@ namespace resp3 { /** \brief A node in the response tree. * \ingroup classes + * + * Redis responses are the pre-order view of the response tree (see + * https://en.wikipedia.org/wiki/Tree_traversal#Pre-order,_NLR). */ struct node { /// The RESP3 type of the data in this node. diff --git a/include/aedis/resp3/serializer.hpp b/include/aedis/resp3/serializer.hpp index b295c7d2..f80a033b 100644 --- a/include/aedis/resp3/serializer.hpp +++ b/include/aedis/resp3/serializer.hpp @@ -21,39 +21,27 @@ namespace aedis { namespace resp3 { -/** @brief Serializes user data into a redis request. +/** @brief Creates a RESP3 request from user data. * \ingroup classes * * A request is composed of one or more redis commands and is * referred to in the redis documentation as a pipeline, see - * https://redis.io/topics/pipelining. + * https://redis.io/topics/pipelining, for example + * + * @code + * serializer sr; + * sr.push(command::hello, 3); + * sr.push(command::flushall); + * sr.push(command::ping); + * sr.push(command::incr, "key"); + * sr.push(command::quit); + * co_await async_write(socket, buffer(sr.request())); + * @endcode * * This class also maintains an internal queue of already added * commands to assist users processing the response to each - * individual command contained in the request. The element type of - * this queue is passed as a template parameter in the request class. - * For example - * - * @code - * request req; - * @endcode - * - * In some cases users need keep more information around for when the - * response arrives, like pointers to http sessions, etc. - * - * @code - * struct element { - * command cmd; - * std::weak_ptr session; - * - * // Required member function. - * command get_command() const noexcept - * {return cmd;} - * }; - * @endcode - * - * Notice users will be required to define the get_command member - * function for their custom types. + * individual command contained in the request see response_queue.cpp + * for simple usage and echo_server.cpp for adavanced usage. */ template class serializer { @@ -67,7 +55,7 @@ public: public: /** \brief Clears the serializer. * - * Note: Already acquired memory won't be released. The is useful + * \remark Already acquired memory won't be released. The is useful * to reusing memory insteam of allocating again each time. */ void clear() @@ -83,13 +71,13 @@ public: /** @brief Appends a new command to the end of the request. * * Non-string types will be converted to string by using - * to_string, which must be made available by the user. + * \c to_string, which must be made available by the user by ADL. */ template void push(ResponseId qelem, Ts const&... args) { // TODO: Should we detect any std::pair in the type in the pack - // to calculate the herader size correctly? + // to calculate the header size correctly? auto constexpr pack_size = sizeof...(Ts); detail::add_header(request_, 1 + pack_size); @@ -107,16 +95,14 @@ public: This overload is useful for commands that have a key. For example \code{.cpp} + std::map map + { {"key1", "value1"} + , {"key2", "value2"} + , {"key3", "value3"} + }; - std::map map - { {"key1", "value1"} - , {"key2", "value2"} - , {"key3", "value3"} - }; - - request req; - req.push_range(command::hset, "key", std::cbegin(map), std::cend(map)); - + request req; + req.push_range(command::hset, "key", std::cbegin(map), std::cend(map)); \endcode */ template @@ -147,13 +133,11 @@ public: example \code{.cpp} + std::set channels + { "channel1" , "channel2" , "channel3" } - std::set channels - { "channel1" , "channel2" , "channel3" } - - request req; - req.push(command::subscribe, std::cbegin(channels), std::cedn(channels)); - + request req; + req.push(command::subscribe, std::cbegin(channels), std::cedn(channels)); \endcode */ template