boost_redis 1.4.2
A redis client library
boost::redis::request Class Reference

Creates Redis requests. More...

#include <include/boost/redis/request.hpp>

Classes

struct  config
 Request configuration options. More...
 

Public Member Functions

 request (config cfg=config{true, false, true, true})
 Constructor. More...
 
void clear ()
 Clears the request preserving allocated memory.
 
auto get_config () const noexcept -> auto const &
 Returns a const reference to the config object.
 
auto get_config () noexcept -> auto &
 Returns a reference to the config object.
 
template<class... Ts>
void push (std::string_view cmd, Ts const &... args)
 Appends a new command to the end of the request. More...
 
template<class Range >
void push_range (std::string_view cmd, Range const &range, decltype(std::cbegin(range)) *=nullptr)
 Appends a new command to the end of the request. More...
 
template<class ForwardIterator >
void push_range (std::string_view const &cmd, ForwardIterator begin, ForwardIterator end, typename std::iterator_traits< ForwardIterator >::value_type *=nullptr)
 Appends a new command to the end of the request. More...
 
template<class ForwardIterator >
void push_range (std::string_view const &cmd, std::string_view const &key, ForwardIterator begin, ForwardIterator end, typename std::iterator_traits< ForwardIterator >::value_type *=nullptr)
 Appends a new command to the end of the request. More...
 
template<class Range >
void push_range (std::string_view const &cmd, std::string_view const &key, Range const &range, decltype(std::begin(range)) *=nullptr)
 Appends a new command to the end of the request. More...
 
void reserve (std::size_t new_cap=0)
 Calls std::string::reserve on the internal storage.
 

Related Functions

(Note that these are not member functions.)

void boost_redis_to_bulk (std::string &payload, std::string_view data)
 Adds a bulk to the request. More...
 

Detailed Description

Creates Redis requests.

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. For example

r.push("HELLO", 3);
r.push("FLUSHALL");
r.push("PING");
r.push("PING", "key");
r.push("QUIT");
Creates Redis requests.
Definition: request.hpp:46
void push(std::string_view cmd, Ts const &... args)
Appends a new command to the end of the request.
Definition: request.hpp:141
Remarks

Uses a std::string for internal storage.

Definition at line 46 of file request.hpp.


Class Documentation

◆ boost::redis::request::config

struct boost::redis::request::config

Request configuration options.

Definition at line 49 of file request.hpp.

Class Members
bool cancel_if_not_connected If true the request will complete with boost::redis::error::not_connected if async_exec is called before the connection with Redis was established.
bool cancel_if_unresponded If false boost::redis::connection::async_exec will not automatically cancel this request if the connection is lost. Affects only requests that have been written to the socket but remained unresponded when boost::redis::connection::async_run completed.
bool cancel_on_connection_lost If true boost::redis::connection::async_exec will complete with error if the connection is lost. Affects only requests that haven't been sent yet.
bool hello_with_priority If this request has a HELLO command and this flag is true, the boost::redis::connection will move it to the front of the queue of awaiting requests. This makes it possible to send HELLO and authenticate before other commands are sent.

Constructor & Destructor Documentation

◆ request()

boost::redis::request::request ( config  cfg = config{true, false, true, true})
inlineexplicit

Constructor.

Parameters
cfgConfiguration options.

Definition at line 84 of file request.hpp.

Member Function Documentation

◆ push()

template<class... Ts>
void boost::redis::request::push ( std::string_view  cmd,
Ts const &...  args 
)
inline

Appends a new command to the end of the request.

For example

request req;
req.push("SET", "key", "some string", "EX", "2");

will add the set command with value "some string" and an expiration of 2 seconds.

Parameters
cmdThe command e.g redis or sentinel command.
argsCommand arguments.
Template Parameters
TsNon-string types will be converted to string by calling boost_redis_to_bulk on each argument. This function must be made available over ADL and must have the following signature
void boost_redis_to_bulk(std::string& to, T const& t);
{
boost::redis::resp3::boost_redis_to_bulk(to, serialize(t));
}
void boost_redis_to_bulk(std::string &payload, std::string_view data)
Adds a bulk to the request.

See cpp20_serialization.cpp

Definition at line 141 of file request.hpp.

◆ push_range() [1/4]

template<class Range >
void boost::redis::request::push_range ( std::string_view  cmd,
Range const &  range,
decltype(std::cbegin(range)) *  = nullptr 
)
inline

Appends a new command to the end of the request.

Equivalent to the overload taking a range of begin and end iterators.

Parameters
cmdRedis command.
rangeRange to send e.g. std::map.
Template Parameters
Atype that can be passed to std::cbegin() and std::cend().

Definition at line 293 of file request.hpp.

◆ push_range() [2/4]

template<class ForwardIterator >
void boost::redis::request::push_range ( std::string_view const &  cmd,
ForwardIterator  begin,
ForwardIterator  end,
typename std::iterator_traits< ForwardIterator >::value_type *  = nullptr 
)
inline

Appends a new command to the end of the request.

This overload is useful for commands that have a dynamic number of arguments and don't have a key. For example

std::set<std::string> channels
{ "channel1" , "channel2" , "channel3" }
request req;
req.push("SUBSCRIBE", std::cbegin(channels), std::cend(channels));
Parameters
cmdThe Redis command
beginIterator to the begin of the range.
endIterator to the end of the range.
Template Parameters
ForwardIteratorIf the value type is not a std::string it will be converted to a string by calling boost_redis_to_bulk. This function must be made available over ADL and must have the following signature
void boost_redis_to_bulk(std::string& to, T const& t);
{
boost::redis::resp3::boost_redis_to_bulk(to, serialize(t));
}

See cpp20_serialization.cpp

Definition at line 237 of file request.hpp.

◆ push_range() [3/4]

template<class ForwardIterator >
void boost::redis::request::push_range ( std::string_view const &  cmd,
std::string_view const &  key,
ForwardIterator  begin,
ForwardIterator  end,
typename std::iterator_traits< ForwardIterator >::value_type *  = nullptr 
)
inline

Appends a new command to the end of the request.

This overload is useful for commands that have a key and have a dynamic range of arguments. For example

std::map<std::string, std::string> map
{ {"key1", "value1"}
, {"key2", "value2"}
, {"key3", "value3"}
};
request req;
req.push_range("HSET", "key", std::cbegin(map), std::cend(map));
request(config cfg=config{true, false, true, true})
Constructor.
Definition: request.hpp:84
Parameters
cmdThe command e.g. Redis or Sentinel command.
keyThe command key.
beginIterator to the begin of the range.
endIterator to the end of the range.
Template Parameters
TsNon-string types will be converted to string by calling boost_redis_to_bulk on each argument. This function must be made available over ADL and must have the following signature
void boost_redis_to_bulk(std::string& to, T const& t);
{
boost::redis::resp3::boost_redis_to_bulk(to, serialize(t));
}

See cpp20_serialization.cpp

Definition at line 184 of file request.hpp.

◆ push_range() [4/4]

template<class Range >
void boost::redis::request::push_range ( std::string_view const &  cmd,
std::string_view const &  key,
Range const &  range,
decltype(std::begin(range)) *  = nullptr 
)
inline

Appends a new command to the end of the request.

Equivalent to the overload taking a range of begin and end iterators.

Parameters
cmdRedis command.
keyRedis key.
rangeRange to send e.g. std::map.
Template Parameters
Atype that can be passed to std::cbegin() and std::cend().

Definition at line 271 of file request.hpp.

Friends And Related Function Documentation

◆ boost_redis_to_bulk()

void boost_redis_to_bulk ( std::string &  payload,
std::string_view  data 
)
related

Adds a bulk to the request.

This function is useful in serialization of your own data structures in a request. For example

void boost_redis_to_bulk(std::string& payload, mystruct const& obj)
{
auto const str = // Convert obj to a string.
boost_redis_to_bulk(payload, str);
}
Parameters
payloadStorage on which data will be copied into.
dataData that will be serialized and stored in payload.

See more in serialization.


The documentation for this class was generated from the following files: