Requests and responses
Requests
Redis requests are composed of one or more commands. In the Redis documentation, requests are called pipelines. For example:
// 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 by
connection::async_exec
as already stated. Requests accept a boost::redis::request::config
object when constructed that dictates how requests are handled in situations like
reconnection. The reader is advised to read it carefully.
Responses
Boost.Redis uses the following strategy to deal with Redis responses:
-
boost::redis::responseshould be used when the request’s number of commands is known at compile-time. -
boost::redis::generic_responseshould be used when the number of commands is dynamic.
For example, the request below has three commands:
request req;
req.push("PING");
req.push("INCR", "key");
req.push("QUIT");
Therefore, its response will also contain three elements. The following response object can be used:
response<std::string, int, std::string>
The response behaves as a std::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:
// Ignore the second and last responses.
response<std::string, ignore_t, std::string, ignore_t>
The following table provides the RESP3-types returned by some Redis commands:
Command |
RESP3 type |
Documentation |
|
Number |
|
|
Array |
|
|
Simple-string, null or blob-string |
|
|
Blob-string |
|
|
Set |
|
|
Map |
To map these RESP3 types into a C++ data structure use the table below:
RESP3 type |
Possible C++ type |
Type |
Simple-string |
|
Simple |
Simple-error |
|
Simple |
Blob-string |
|
Simple |
Blob-error |
|
Simple |
Number |
|
Simple |
Double |
|
Simple |
Null |
|
Simple |
Array |
|
Aggregate |
Map |
|
Aggregate |
Set |
|
Aggregate |
Push |
|
Aggregate |
For example, the response to the request
request req;
req.push("HELLO", 3);
req.push_range("RPUSH", "key1", vec);
req.push_range("HSET", "key2", map);
req.push("LRANGE", "key3", 0, -1);
req.push("HGETALL", "key4");
req.push("QUIT");
Can be read in the following response object:
response<
redis::ignore_t, // hello
int, // rpush
int, // hset
std::vector<T>, // lrange
std::map<U, V>, // hgetall
std::string // quit
> resp;
To execute the request and read the response use
async_exec:
co_await conn->async_exec(req, resp);
If the intention is to ignore responses altogether, use
ignore:
// Ignores the response
co_await conn->async_exec(req, ignore);
Responses that contain nested aggregates or heterogeneous data types will be given special treatment later in the general case. As of this writing, not all RESP3 types are used by the Redis server, which means in practice users will be concerned with a reduced subset of the RESP3 specification.
Pushes
Commands that have no response, like
-
"SUBSCRIBE" -
"PSUBSCRIBE" -
"UNSUBSCRIBE"
must NOT be included in the response tuple. For example, the following request
request req;
req.push("PING");
req.push("SUBSCRIBE", "channel");
req.push("QUIT");
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 use cases,
wrap the type within a std::optional:
response<
std::optional<A>,
std::optional<B>,
...
> resp;
Everything else stays the same.
Transactions
To read responses to transactions we must first observe that Redis
will queue the transaction commands and send their individual
responses as elements of an array. The array itself is the response to
the EXEC command. For example, to read the response to this request
req.push("MULTI");
req.push("GET", "key1");
req.push("LRANGE", "key2", 0, -1);
req.push("HGETALL", "key3");
req.push("EXEC");
Use the following response 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
> // exec
> resp;
For a complete example, see cpp20_containers.cpp.
The general case
There are cases where responses to Redis 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 anintand receiving a blob-string 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.
To deal with these cases Boost.Redis provides the boost::redis::resp3::node type
abstraction, that is the most general form of an element in a
response, be it a simple RESP3 type or the element of an aggregate. It
is defined like:
template <class String>
struct basic_node {
// The RESP3 type of the data in this node.
type data_type;
// The number of elements of an aggregate (or 1 for simple data).
std::size_t aggregate_size;
// The depth of this node in the response tree.
std::size_t depth;
// The actual data. For aggregate types this is always empty.
String value;
};
Any response to a Redis command can be parsed into a boost::redis::generic_response. The vector can be seen as a pre-order view of the response tree. Using it is not different than using other types:
// Receives any RESP3 simple or aggregate data type.
boost::redis::generic_response resp;
co_await conn->async_exec(req, resp);
For example, suppose we want to retrieve a hash data structure
from Redis with HGETALL, some of the options are
-
boost::redis::generic_response: always works. -
std::vector<std::string>: efficient and flat, all elements as string. -
std::map<std::string, std::string>: efficient if you need the data as astd::map. -
std::map<U, V>: efficient if you are storing serialized data. Avoids temporaries and requiresboost_redis_from_bulkforUandV.
In addition to the above users can also use unordered versions of the
containers. The same reasoning applies to sets e.g. SMEMBERS
and other data structures in general.