redis plus plus
redis-plus-plus 1.3.13
中文交流群
我创建了一个名为redis-llm的redis模块，该模块将LLMS（大型语言模型）与Redis集成在一起。您可以通过提出问题来学习Redis Plus-Plus。
这是Redis的C ++客户库。它基于Hiredis，与C ++ 17，C ++ 14和C ++ 11兼容。
注意：我不是母语的人。因此，如果文档尚不清楚，请随时打开问题或提取请求。我会尽快回复。
主分支是稳定的分支，它通过所有测试。开发分支不稳定。如果您想贡献，请在开发分支机构上创建拉动请求。
由于Redis-Plus-Plus基于Hiredis ，因此您应该首先安装Hiredis 。 Hiredis的最低版本要求为v0.12.1 。但是，始终建议使用最新的Hiredis稳定版本。
注意：您必须确保安装了Hiredis的1个版本。否则，您可能会遇到一些有线问题。例如，检查以下问题：第135期，第140期和第158期。
通常，您可以使用C ++软件包管理器安装Hiredis ，这是最简单的方法，例如sudo apt-get install libhiredis-dev 。但是，如果要安装Hiredis的最新代码或指定的版本（例如，需要Hiredis V1.0.0或更高版本），则可以从源安装。
再次注意：不要安装多个版本的Hiredis。
git clone https://github.com/redis/hiredis.git
cd hiredis
make
make install默认情况下， Hiredis安装在/usr /local 。如果要在非默认位置安装Hiredis ，请使用以下命令指定安装路径。
make PREFIX=/non/default/path
make PREFIX=/non/default/path installRedis-Plus-Plus是用Cmake构建的。
git clone https://github.com/sewenew/redis-plus-plus.git
cd redis-plus-plus
mkdir build
cd build
cmake ..
make
make install
cd ..如果HIRDIS安装在非默认位置，则应使用CMAKE_PREFIX_PATH来指定Hiredis的安装路径。默认情况下， redis-plus-plus安装在/usr /local 。但是，您可以使用CMAKE_INSTALL_PREFIX在非默认位置安装redis-plus-plus 。
cmake -DCMAKE_PREFIX_PATH=/path/to/hiredis -DCMAKE_INSTALL_PREFIX=/path/to/install/redis-plus-plus ..由于版本1.3.0，默认情况下，使用-std=c++17标准构建了Redis-Plus-Plus 。这样我们就可以使用std :: string_view和std ::可选功能。但是，它也可以使用-std=c++11或-std=c++14标准构建，在这种情况下，我们拥有自己的std::string_view和std::optional简单实现。为了明确指定C ++标准，您可以使用以下CMAKE标志： -DREDIS_PLUS_PLUS_CXX_STANDARD=11 。
cmake -DCMAKE_PREFIX_PATH=/path/to/hiredis -DCMAKE_INSTALL_PREFIX=/path/to/install/redis-plus-plus -DREDIS_PLUS_PLUS_CXX_STANDARD=11 ..注意：您应该使用相同标准构建Redis-Plus-Plus和应用程序，例如，如果您使用C ++ 17标准构建Redis-Plus-Plus ，则还必须使用C ++ 17标准构建应用程序代码。
编译redis-Plus-Plus时，还会编译一个测试程序，这可能需要一段时间。但是，您可以使用以下CMAKE选项禁用建筑测试： -DREDIS_PLUS_PLUS_BUILD_TEST=OFF 。
cmake -DCMAKE_PREFIX_PATH=/path/to/hiredis -DCMAKE_INSTALL_PREFIX=/path/to/install/redis-plus-plus -DREDIS_PLUS_PLUS_BUILD_TEST=OFF ..默认情况下， redis-plus-plus既构建静态库，又建立共享库。如果您只想构建其中一个，则可以使用-DREDIS_PLUS_PLUS_BUILD_STATIC=OFF或-DREDIS_PLUS_PLUS_BUILD_SHARED=OFF禁用另一个。
Redis-Plus-Plus默认情况下，使用-fPIC选项（即独立代码）构建静态库。但是，您可以使用-DREDIS_PLUS_PLUS_BUILD_STATIC_WITH_PIC=OFF禁用它。
现在， Hiredis拥有Windows支持，自Visual Studio 2017以来，Visual Studio对Cmake具有内置支持。因此， Redis-Plus-Plus现在还支持Windows平台。它已经通过Visual Studio 2017进行了全面测试，后来又在Win 10上进行了测试。我对Visual Studio环境不熟悉，以下DOC可能不准确。如果您熟悉Windows平台，请随时更新有关如何在Windows上安装Redis-Plus-Plus的文档。
以下是有关如何使用Visual Studio 2017或以后构建CMAKE项目的一些链接。如果您不熟悉它，最好先阅读以下说明：
注意：IMHO，Visual Studio 2017对Cmake项目的支持不是很成熟，我建议您使用Visual Studio 2019构建Hiredis和 *Redis-Plus-Plus。
首先，您需要在Master Branch上获取Hiredis的最新代码。旧版本可能不支持Windows平台。 hiredis的cmakelists.txt使用add_compile_definitions方法，仅由cmake 3.12或更高版本支持。但是，Visual Studio 2017的Cmake版本比这更古老。因此，如果您使用的是Visual Studio 2017，则需要在CMakelists.TXT文件中评论以下行：
#IF(WIN32)
# ADD_COMPILE_DEFINITIONS(_CRT_SECURE_NO_WARNINGS WIN32_LEAN_AND_MEAN)
#ENDIF()您可以使用“开放文件夹”功能打开Hiredis项目，并使用上面提到的说明（链接）构建它。
由于Redis-Plus-Plus取决于Hiredis ，因此我们需要在构建其之前指定Hiredis的安装路径。您可以使用“开放文件夹”功能打开Redis-Plus-Plus项目。您需要编辑cmakesetting.json文件（由Visual Studio自动生成），以设置Hiredis_header ， Hiredis_lib和test_hiredis_lib变量，以指定Hiredis标头的安装路径，HIRIRIDIS Dynamic库的安装路径和Hiredis static static stitic库的安装路径。以下是cmakesetting.json文件的示例：
{
"configurations" : [
{
"name" : " x64-Release " ,
"generator" : " Visual Studio 15 2017 Win64 " ,
"configurationType" : " Release " ,
"buildRoot" : " ${env.LOCALAPPDATA} \ CMakeBuild \ ${workspaceHash} \ build \ ${name} " ,
"cmakeCommandArgs" : " " ,
"buildCommandArgs" : " -m -v:minimal " ,
"variables" : [
{
"name" : " HIREDIS_HEADER " ,
"value" : " installation path of hiredis header files " ,
"type" : " PATH "
},
{
"name" : " HIREDIS_LIB " ,
"value" : " installation path of dynamic library of hiredis " ,
"type" : " FILEPATH "
},
{
"name" : " TEST_HIREDIS_LIB " ,
"value" : " installation path of static library of hiredis " ,
"type" : " FILEPATH "
}
]
}
]
}然后，您可以构建上述指令（链接）。如果您在调试模式下使用Visual Studio 2017进行构建，则在构建测试时可能会出现 /BIGOBJ错误。在这种情况下，您可以通过设置-DREDIS_PLUS_PLUS_BUILD_TEST=OFF或以发布模式构建建筑物测试。
笔记：
REDIS_PLUS_PLUS_CXX_STANDARD CMAKE选项设置为11。如果您想通过Visual Studio构建该项目并对其有疑问，请按照以下步骤操作。以下是在Visual Studio 2022社区中测试的。
# download two projects into this folder
mkdir redis ++
cd redis ++
# make sure you create a hiredis first to work as a library
mkdir hiredis - lib
cd hiredis - lib
mkdir lib
git clone https: // github.com / redis / hiredis.git
cd hiredis到目前为止，每个步骤都应该很好。然后打开CMakeLists.txt文件。修改以下行并评论
...
# SET(CMAKE_DEBUG_POSTFIX d)
...然后回到Hiredis项目文件夹
mkdir build
cd build
# convert project into visual studio 2022, if necessary choose you version e.g 19 2019 etc.
cmake - G " Visual Studio 17 2022 " ..
. / hiredis.sln将hiredis设置为启动项目，然后在调试模式下单击Build Solution
成功构建后，将Debug中的所有文件复制到hiredis-lib/lib文件夹中
在这里，Hiredis的工作应该完成。
然后返回redis++文件夹。在这里开放终端
git clone https: // github.com / sewenew / redis - plus - plus.git
cd redis - plus - plus
mkdir build
cd build现在，您应该始终在PC上使用OpenSSL，否则可以使用Chocolatey安装它。对于Visual Studio 2022，请使用vpckg单独安装Pthread，遵循此链接
毕竟准备。如果您想转换所有项目，则
cmake - DCMAKE_PREFIX_PATH = " $ ( ABSOLUTE_PATH ) hiredis-lib " - G " Visual Studio 17 2022 " ..
cd build
. / redis ++ .sln将redis++_static设置为启动项目，然后单击Build Solution
到目前为止，构建已成功完成！
在Windows平台上，如果您的应用程序代码还需要包括Windows.h 。您必须确保SW/REDIS ++/REDIS ++。 hWindows.h之前包含H。检查此问题以获取细节。
使用CMAKE提供了建立GNU/Debian软件包的基本支持。以下示例显示了如何构建Debian软件包：
mkdir build ; cd build
cmake ..
cpack -G DEB安装前缀可以修改如下：
mkdir build ; cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
cpack -G DEBRedis-Plus-Plus已通过以下编译器进行了全面测试：
gcc version 4.8.5 20150623 (Red Hat 4.8.5-39) (GCC)
gcc version 5.5.0 20171010 (Ubuntu 5.5.0-12ubuntu1)
gcc version 6.5.0 20181026 (Ubuntu 6.5.0-2ubuntu1~18.04)
gcc version 7.4.0 (Ubuntu 7.4.0-1ubuntu1~18.04.1)
gcc version 8.3.0 (Ubuntu 8.3.0-6ubuntu1~18.04.1)
gcc version 9.2.1 20191008 (Ubuntu 9.2.1-9ubuntu2)
gcc version 10.2.1 20210110 (Debian 10.2.1-6)
clang version 3.9.1-19ubuntu1 (tags/RELEASE_391/rc2)
clang version 4.0.1-10 (tags/RELEASE_401/final)
clang version 5.0.1-4 (tags/RELEASE_501/final)
clang version 6.0.0-1ubuntu2 (tags/RELEASE_600/final)
clang version 7.0.0-3~ubuntu0.18.04.1 (tags/RELEASE_700/final)
clang version 8.0.1-3build1 (tags/RELEASE_801/final)
Apple clang version 11.0.0 (clang-1100.0.33.12)
Visual Studio 2017 (Win 10)
Visual Studio 2019 (Win 10)如果使用-DREDIS_PLUS_PLUS_BUILD_TEST=ON构建Redis -Plus -Plus （默认行为，并且可以使用-DREDIS_PLUS_PLUS_BUILD_TEST=OFF ），则可以在build/test Directory中获得一个测试程序： build/test/test/test_redis++ 。
为了运行测试，您需要设置一个redis实例和redis群集。由于测试程序将将大部分REDIS命令发送到服务器和群集，因此您需要设置最新版本的Redis。否则，测试可能会失败。例如，如果您设置了REDIS 4.0进行测试，则测试程序试图将ZPOPMAX命令（REDIS 5.0命令）发送到服务器时将失败。如果要使用其他REDIS版本运行测试，则必须评论Redis redis尚未支持的命令，从redis-plus-plus-plus/test/src/src/src/sw/sw/redis ++/目录中的测试源文件。不便之处，抱歉，我将解决此问题，以使测试程序将来与任何版本的REDIS一起使用。
注意：REDIS的最新版本只是运行测试的要求。实际上，您可以使用任何版本的redis使用redis-Plus-plus ，即Redis 2.0及更高版本。
切勿在生产胎儿中运行测试程序，因为测试程序读取或写入的密钥可能与您的应用程序相抵触。
为了使用REDIS和REDIS群集进行测试，您可以使用以下命令运行测试程序：
./build/test/test_redis++ -h host -p port -a auth -n cluster_node -c cluster_port如果您只想使用REDIS进行测试，则只需要指定主机，端口和验证选项：
./build/test/test_redis++ -h host -p port -a auth同样，如果您只想使用REDIS群集运行测试，则只需指定Cluster_Node ， Cluster_Port和Auth Optoct：
./build/test/test_redis++ -a auth -n cluster_node -c cluster_port默认情况下，测试程序不会在多线程环境中测试运行Redis-Plus-Plus 。如果您想进行多线程测试，这可能需要很长时间，则可以指定-m选项：
./build/test/test_redis++ -h host -p port -a auth -n cluster_node -c cluster_port -m如果所有测试都通过了，则测试程序将打印以下消息：
Pass all tests否则，它将打印错误消息。
Redis-Plus-Plus的运行速度与Hiredis一样快，因为它是Hiredis的包装纸。您可以在基准模式下运行test_redis ++以检查环境中的性能。
./build/test/test_redis++ -h host -p port -a auth -n cluster_node -c cluster_port -b -t thread_num -s connection_pool_size -r request_num -k key_len -v val_len10 。5默认情况下。100000 。10 。10 。 Bechmark将生成100随机二进制键进行测试，这些键的大小由Key_Len指定。当基准运行时，它将用这些键读/写。因此，切勿在生产环境中运行测试程序，否则，它可能会删除数据。
编译代码后，您将同时获得共享库和静态库。由于Redis-Plus-Plus取决于Hiredis ，因此您需要将两个库将其链接到您的应用程序。另外，不要忘记指定C ++标准， -std=c++17 ， -std=c++14或-std=c++11 ，以及与线程相关的选项。
以GCC为例。
g++ -std=c++17 -o app app.cpp /path/to/libredis++.a /path/to/libhiredis.a -pthread如果在非默认位置安装了Hiredis和Redis-Plus-Plus ，则应使用-I选项来指定标题路径。
g++ -std=c++17 -I/non-default/install/include/path -o app app.cpp /path/to/libredis++.a /path/to/libhiredis.a -pthreadg++ -std=c++17 -o app app.cpp -lredis++ -lhiredis -pthread如果在非默认位置安装了Hiredis和redis-plus-plus ，则应使用-I和-L选项指定标题和库路径。
g++ -std=c++17 -I/non-default/install/include/path -L/non-default/install/lib/path -o app app.cpp -lredis++ -lhiredis -pthread与共享库链接并运行应用程序时，您可能会收到以下错误消息：
error while loading shared libraries: xxx: cannot open shared object file: No such file or directory.那是因为链接器找不到共享库。为了解决问题，您可以添加安装Hiredis和Redis-Plus-Plus库的路径，并将其添加到LD_LIBRARY_PATH环境变量中。例如：
export LD_LIBRARY_PATH= $LD_LIBRARY_PATH :/usr/local/lib检查此Stackoverflow问题，以获取有关如何解决问题的详细信息。
如果您使用cmake来构建应用程序，则需要在cmakelists.txt中添加hiredis和redis-plus-plus依赖项：
# <---------- set c++ standard ------------->
# NOTE: you must build redis-plus-plus and your application code with the same standard.
set (CMAKE_CXX_STANDARD 17)
set (CMAKE_CXX_STANDARD_REQUIRED ON )
# <------------ add hiredis dependency --------------->
find_path (HIREDIS_HEADER hiredis)
target_include_directories ( target PUBLIC ${HIREDIS_HEADER} )
find_library (HIREDIS_LIB hiredis)
target_link_libraries ( target ${HIREDIS_LIB} )
# <------------ add redis-plus-plus dependency -------------->
# NOTE: this should be *sw* NOT *redis++*
find_path (REDIS_PLUS_PLUS_HEADER sw)
target_include_directories ( target PUBLIC ${REDIS_PLUS_PLUS_HEADER} )
find_library (REDIS_PLUS_PLUS_LIB redis++)
target_link_libraries ( target ${REDIS_PLUS_PLUS_LIB} )有关cmakelists.txt的完整示例，请参见此问题。
另外，如果您在非默认位置安装了Hiredis和redis-plus-plus ，则需要使用CMAKE_PREFIX_PATH选项运行CMake，以指定这两个库的安装路径。
cmake -DCMAKE_PREFIX_PATH=/installation/path/to/the/two/libs ..
# include < sw/redis++/redis++.h >
using namespace sw ::redis ;
try {
// Create an Redis object, which is movable but NOT copyable.
auto redis = Redis ( " tcp://127.0.0.1:6379 " );
// ***** STRING commands *****
redis. set ( " key " , " val " );
auto val = redis. get ( " key " ); // val is of type OptionalString. See 'API Reference' section for details.
if (val) {
// Dereference val to get the returned value of std::string type.
std::cout << *val << std::endl;
} // else key doesn't exist.
// ***** LIST commands *****
// std::vector<std::string> to Redis LIST.
std::vector<std::string> vec = { " a " , " b " , " c " };
redis. rpush ( " list " , vec. begin (), vec. end ());
// std::initializer_list to Redis LIST.
redis. rpush ( " list " , { " a " , " b " , " c " });
// Redis LIST to std::vector<std::string>.
vec. clear ();
redis. lrange ( " list " , 0 , - 1 , std::back_inserter (vec));
// ***** HASH commands *****
redis. hset ( " hash " , " field " , " val " );
// Another way to do the same job.
redis. hset ( " hash " , std::make_pair ( " field " , " val " ));
// std::unordered_map<std::string, std::string> to Redis HASH.
std::unordered_map<std::string, std::string> m = {
{ " field1 " , " val1 " },
{ " field2 " , " val2 " }
};
redis. hmset ( " hash " , m. begin (), m. end ());
// Redis HASH to std::unordered_map<std::string, std::string>.
m. clear ();
redis. hgetall ( " hash " , std::inserter (m, m. begin ()));
// Get value only.
// NOTE: since field might NOT exist, so we need to parse it to OptionalString.
std::vector<OptionalString> vals;
redis. hmget ( " hash " , { " field1 " , " field2 " }, std::back_inserter (vals));
// ***** SET commands *****
redis. sadd ( " set " , " m1 " );
// std::unordered_set<std::string> to Redis SET.
std::unordered_set<std::string> set = { " m2 " , " m3 " };
redis. sadd ( " set " , set. begin (), set. end ());
// std::initializer_list to Redis SET.
redis. sadd ( " set " , { " m2 " , " m3 " });
// Redis SET to std::unordered_set<std::string>.
set. clear ();
redis. smembers ( " set " , std::inserter (set, set. begin ()));
if (redis. sismember ( " set " , " m1 " )) {
std::cout << " m1 exists " << std::endl;
} // else NOT exist.
// ***** SORTED SET commands *****
redis. zadd ( " sorted_set " , " m1 " , 1.3 );
// std::unordered_map<std::string, double> to Redis SORTED SET.
std::unordered_map<std::string, double > scores = {
{ " m2 " , 2.3 },
{ " m3 " , 4.5 }
};
redis. zadd ( " sorted_set " , scores. begin (), scores. end ());
// Redis SORTED SET to std::vector<std::pair<std::string, double>>.
// NOTE: The return results of zrangebyscore are ordered, if you save the results
// in to `std::unordered_map<std::string, double>`, you'll lose the order.
std::vector<std::pair<std::string, double >> zset_result;
redis. zrangebyscore ( " sorted_set " ,
UnboundedInterval< double >{}, // (-inf, +inf)
std::back_inserter (zset_result));
// Only get member names:
// pass an inserter of std::vector<std::string> type as output parameter.
std::vector<std::string> without_score;
redis. zrangebyscore ( " sorted_set " ,
BoundedInterval< double >( 1.5 , 3.4 , BoundType::CLOSED), // [1.5, 3.4]
std::back_inserter (without_score));
// Get both member names and scores:
// pass an back_inserter of std::vector<std::pair<std::string, double>> as output parameter.
std::vector<std::pair<std::string, double >> with_score;
redis. zrangebyscore ( " sorted_set " ,
BoundedInterval< double >( 1.5 , 3.4 , BoundType::LEFT_OPEN), // (1.5, 3.4]
std::back_inserter (with_score));
// ***** SCRIPTING commands *****
// Script returns a single element.
auto num = redis. eval < long long >( " return 1 " , {}, {});
// Script returns an array of elements.
std::vector<std::string> nums;
redis. eval ( " return {ARGV[1], ARGV[2]} " , {}, { " 1 " , " 2 " }, std::back_inserter (nums));
// mset with TTL
auto mset_with_ttl_script = R"(
local len = #KEYS
if (len == 0 or len + 1 ~= #ARGV) then return 0 end
local ttl = tonumber(ARGV[len + 1])
if (not ttl or ttl <= 0) then return 0 end
for i = 1, len do redis.call("SET", KEYS[i], ARGV[i], "EX", ttl) end
return 1
)" ;
// Set multiple key-value pairs with TTL of 60 seconds.
auto keys = { " key1 " , " key2 " , " key3 " };
std::vector<std::string> args = { " val1 " , " val2 " , " val3 " , " 60 " };
redis. eval < long long >(mset_with_ttl_script, keys. begin (), keys. end (), args. begin (), args. end ());
// ***** Pipeline *****
// Create a pipeline.
auto pipe = redis. pipeline ();
// Send mulitple commands and get all replies.
auto pipe_replies = pipe . set ( " key " , " value " )
. get ( " key " )
. rename ( " key " , " new-key " )
. rpush ( " list " , { " a " , " b " , " c " })
. lrange ( " list " , 0 , - 1 )
. exec ();
// Parse reply with reply type and index.
auto set_cmd_result = pipe_replies. get < bool >( 0 );
auto get_cmd_result = pipe_replies. get <OptionalString>( 1 );
// rename command result
pipe_replies. get < void >( 2 );
auto rpush_cmd_result = pipe_replies. get < long long >( 3 );
std::vector<std::string> lrange_cmd_result;
pipe_replies. get ( 4 , back_inserter (lrange_cmd_result));
// ***** Transaction *****
// Create a transaction.
auto tx = redis. transaction ();
// Run multiple commands in a transaction, and get all replies.
auto tx_replies = tx. incr ( " num0 " )
. incr ( " num1 " )
. mget ({ " num0 " , " num1 " })
. exec ();
// Parse reply with reply type and index.
auto incr_result0 = tx_replies. get < long long >( 0 );
auto incr_result1 = tx_replies. get < long long >( 1 );
std::vector<OptionalString> mget_cmd_result;
tx_replies. get ( 2 , back_inserter (mget_cmd_result));
// ***** Generic Command Interface *****
// There's no *Redis::client_getname* interface.
// But you can use *Redis::command* to get the client name.
val = redis. command <OptionalString>( " client " , " getname " );
if (val) {
std::cout << *val << std::endl;
}
// Same as above.
auto getname_cmd_str = { " client " , " getname " };
val = redis. command <OptionalString>(getname_cmd_str. begin (), getname_cmd_str. end ());
// There's no *Redis::sort* interface.
// But you can use *Redis::command* to send sort the list.
std::vector<std::string> sorted_list;
redis. command ( " sort " , " list " , " ALPHA " , std::back_inserter (sorted_list));
// Another *Redis::command* to do the same work.
auto sort_cmd_str = { " sort " , " list " , " ALPHA " };
redis. command (sort_cmd_str. begin (), sort_cmd_str. end (), std::back_inserter (sorted_list));
// ***** Redis Cluster *****
// Create a RedisCluster object, which is movable but NOT copyable.
auto redis_cluster = RedisCluster ( " tcp://127.0.0.1:7000 " );
// RedisCluster has similar interfaces as Redis.
redis_cluster. set ( " key " , " value " );
val = redis_cluster. get ( " key " );
if (val) {
std::cout << *val << std::endl;
} // else key doesn't exist.
// Keys with hash-tag.
redis_cluster. set ( " key{tag}1 " , " val1 " );
redis_cluster. set ( " key{tag}2 " , " val2 " );
redis_cluster. set ( " key{tag}3 " , " val3 " );
std::vector<OptionalString> hash_tag_res;
redis_cluster. mget ({ " key{tag}1 " , " key{tag}2 " , " key{tag}3 " },
std::back_inserter (hash_tag_res));
} catch ( const Error &e) {
// Error handling.
}您还可以查看redis.h以获取Doxygen样式文档。
Redis类维护一个连接池到Redis服务器。如果连接断开， Redis会自动重新连接到Redis服务器。
您可以使用ConnectionOptions和ConnectionPoolOptions初始化Redis实例。 ConnectionOptions指定了连接到Redis服务器的选项，并且ConnectionPoolOptions指定了Conneciton池的选项。 ConnectionPoolOptions是可选的。如果未指定， Redis将保持与Redis服务器的单个连接。
ConnectionOptions connection_options;
connection_options.host = " 127.0.0.1 " ; // Required.
connection_options.port = 6666 ; // Optional. The default port is 6379.
connection_options.password = " auth " ; // Optional. No password by default.
connection_options.db = 1 ; // Optional. Use the 0th database by default.
// Optional. Timeout before we successfully send request to or receive response from redis.
// By default, the timeout is 0ms, i.e. never timeout and block until we send or receive successfuly.
// NOTE: if any command is timed out, we throw a TimeoutError exception.
connection_options.socket_timeout = std::chrono::milliseconds( 200 );
// Connect to Redis server with a single connection.
Redis redis1 (connection_options);
ConnectionPoolOptions pool_options;
pool_options.size = 3 ; // Pool size, i.e. max number of connections.
// Optional. Max time to wait for a connection. 0ms by default, which means wait forever.
// Say, the pool size is 3, while 4 threds try to fetch the connection, one of them will be blocked.
pool_options.wait_timeout = std::chrono::milliseconds( 100 );
// Optional. Max lifetime of a connection. 0ms by default, which means never expire the connection.
// If the connection has been created for a long time, i.e. more than `connection_lifetime`,
// it will be expired and reconnected.
pool_options.connection_lifetime = std::chrono::minutes( 10 );
// Connect to Redis server with a connection pool.
Redis redis2 (connection_options, pool_options);注意：如果设置ConnectionOptions::socket_timeout ，然后尝试调用blocking命令，例如Redis::brpop ， Redis::blpop ， Redis::bzpopmax ， Redis::bzpopmin ，则必须确保ConnectionOptions::socket_timeout比这些封锁命令所指定的超时。否则，您可能会获得TimeoutError并丢失消息。
有关更多选项，请参见ConnectionOptions和ConnectionPoolOptions。另请参阅第80期有关连接池的讨论。
注意： Redis类是可移动的，但不能复制。
// auto redis3 = redis1; // this won't compile.
// But it's movable.
auto redis3 = std::move(redis1);Redis-Plus-Plus还支持使用UNIX域套接字连接到Redis服务器。
ConnectionOptions options;
options.type = ConnectionType::UNIX;
options.path = " /path/to/socket " ;
Redis redis (options);您也可以使用URI连接到Redis服务器：
tcp://[[username:]password@]host[:port][/db]
redis://[[username:]password@]host[:port][/db]
unix://[[username:]password@]path-to-unix-domain-socket[/db]
需要该方案和主机零件，而其他零件则是可选的。如果您使用UNIX域插座连接到REDIS，则应使用UNIX方案，否则，应使用TCP或REDIS方案。以下是这些可选零件的默认值列表：
注意：如果您的密码或用户名包含“@”，或者您的用户名包含'：'，则无法使用URI构造Redis对象。因为Redis-Plus-Plus会错误地解析URI。在这种情况下，您需要使用ConnectionOptions构建Redis对象。
注意：REDIS 6.0支持ACL，您可以为连接指定用户名。但是，在Redis 6.0之前，您无法做到这一点。
另外，可以使用URI的查询字符串指定以下连接选项和连接池选项，例如tcp：//127.0.0.1？keep_alive = true＆socket_time_timeout = 100ms＆connect_time_timeout = 100ms ：
| 选项 | 范围 | 默认 |
|---|---|---|
ConnectionOptions::user | 用户 | 默认 |
ConnectionOptions::password | 密码 | 空字符串，即没有密码 |
ConnectionOptions::db | DB | 0 |
ConnectionOptions::keep_alive | keep_alive | 错误的 |
ConnectionOptions::connect_timeout | connect_timeout | 0ms |
ConnectionOptions::socket_timeout | socket_timeout | 0ms |
ConnectionOptions::resp | 解答 | 2 |
ConnectionPoolOptions::size | pool_size | 1 |
ConnectionPoolOptions::wait_timeout | pool_wait_timeout | 0ms |
ConnectionPoolOptions::connection_lifetime | pool_connection_lifetime | 0ms |
ConnectionPoolOptions::connection_idle_time | pool_connection_idle_time | 0ms |
笔记：
// Single connection to the given host and port.
Redis redis1 ( " tcp://127.0.0.1:6666 " );
// Use default port, i.e. 6379.
Redis redis2 ( " tcp://127.0.0.1 " );
// Connect to Redis with password, and default port.
Redis redis3 ( " tcp://[email protected] " );
// Connect to Redis and select the 2nd (db number starts from 0) database.
Redis redis4 ( " tcp://127.0.0.1:6379/2 " );
// Set keep_alive option to true with query string.
Redis redis5 ( " tcp://127.0.0.1:6379/2?keep_alive=true " );
// Set socket_timeout to 50 milliseconds, and connect_timeout to 1 second with query string.
Redis redis6 ( " tcp://127.0.0.1?socket_timeout=50ms&connect_timeout=1s " );
// Connect to Unix Domain Socket.
Redis redis7 ( " unix://path/to/socket " );自REDIS 6.0以来，它支持REDIS协议的新版本，即RESS3。为了使用此新协议，您需要将ConnectionOptions::resp设置为3。
ConnectionOptions opts;
opts.resp = 3;
// Set other options...
默认情况下， ConnectionOptions::resp是2，IE使用RESS版本2。到目前为止，仅支持2和3版本，并且如果您设置了ConnectionOptions::resp其他数字，则该行为是不确定的。
注意：为了使用此新协议，您需要安装最新的Hiredis（即使是Hiredis-V1.0.2也有reves3支持的错误）。
游泳池中的连接是懒惰的。初始化连接池时，即Redis的构造函数， Redis不会连接到服务器。相反，仅当您尝试发送命令时，它才连接到服务器。这样，我们可以避免不必要的连接。因此，如果池大小为5，但最大并发连接的数量为3，则池中只有3个连接。
您无需检查Redis对象是否成功连接到服务器。如果Redis无法创建与Redis服务器的连接，或者在某个时候断开该连接，则当您尝试使用Redis发送命令时，它会引发类型Error的例外。即使您有例外，即连接破裂，也无需创建一个新的Redis对象。您可以重复使用Redis对象发送命令， Redis对象将尝试自动重新连接到服务器。如果它成功重新连接，则将命令发送到服务器。否则，它再次引发异常。
有关异常的详细信息，请参见异常部分。
创建Redis对象并不便宜，因为它将创建与Redis服务器的新连接。因此，您最好尽可能多地重用Redis对象。此外，可以在多线程环境中调用Redis的成员功能，并且您可以在多个线程中共享Redis对象。
// This is GOOD practice.
auto redis = Redis( " tcp://127.0.0.1 " );
for ( auto idx = 0 ; idx < 100 ; ++idx) {
// Reuse the Redis object in the loop.
redis. set ( " key " , " val " );
}
// This is VERY BAD! It's very inefficient.
// NEVER DO IT!!!
for ( auto idx = 0 ; idx < 100 ; ++idx) {
// Create a new Redis object for each iteration.
auto redis = Redis ( " tcp://127.0.0.1 " );
redis. set ( " key " , " val " );
}Redis-Plus-Plus还具有TLS支持。但是，为了使用此功能，您需要在构建Hiredis和Redis-Plus-Plus时启用它。
注意：到目前为止，尚未在Windows平台上测试TLS功能。将来我将修复它。
在用TLS支持构建Hiredis时，您需要下载版本V1.0.0或后者的Hiredis ，并指定USE_SSL=1标志：
make PREFIX=/non/default/path USE_SSL=1
make PREFIX=/non/default/path USE_SSL=1 install然后，您可以通过指定-dredis_plus_plus_use_tls -DREDIS_PLUS_PLUS_USE_TLS=ON Option：
cmake -DREDIS_PLUS_PLUS_USE_TLS=ON ..为了通过TLS支持连接到REDIS，您需要指定以下连接选项：
ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
opts.tls.enabled = true ; // Required. `false` by default.
opts.tls.cert = " /path/to/client/certificate " ; // Optional
opts.tls.key = " /path/to/private/key/file " ; // Optional
opts.tls.cacert = " /path/to/CA/certificate/file " ; // You can also set `opts.tls.cacertdir` instead.
opts.tls.sni = " server-name-indication " ; // Optional尽管tls.cert和tls.key是可选的，但如果指定其中一个，则还必须指定另一个。您还可以指定存储证书的目录，而不是指定tls.cacert ，而是指定tls.cacertdir 。
这些选项与redis-cli的TLS相关命令行参数相同，因此您还可以运行redis-cli --help以获取这些选项的详细说明。
然后，您可以使用此ConnectionOptions创建一个Redis对象，以通过TLS支持连接到Redis服务器。
注意：构建应用程序代码时，您还需要将其与libhiredis.a ， libhiredis_ssl.a ， libredis++.a （或相应的共享库）， -lssl和-lcrypto链接。
默认情况下， redis-plus-plus会自动初始化openssl库，即调用SSL_library_init ，并在需要时初始化锁。但是，您的应用程序代码可能已经初始化了OpenSSL库。在这种情况下，您可以调用tls::disable_auto_init()禁用初始化。您应仅调用此功能一次，然后在任何其他Redis-Plus Plus操作之前调用它。否则，行为是不确定的。
自Hiredis v1.1.0以来，它支持跳过证书验证。如果要与Redis-Plus-Plus一起使用此功能，则可以检查此问题以获取示例。
您可以通过Redis对象发送redis命令。 Redis对于每个Redis命令都有一种或多种（超载）方法。该方法的名称与相应的命令相同（较低）。例如，我们有3种为DEL key [key ...]命令的超载方法：
// Delete a single key.
long long Redis::del ( const StringView &key);
// Delete a batch of keys: [first, last).
template < typename Input>
long long Redis::del (Input first, Input last);
// Delete keys in the initializer_list.
template < typename T>
long long Redis::del (std::initializer_list<T> il);使用输入参数，这些方法基于REDIS协议构建了REDIS命令，并将命令发送到Redis服务器。然后同步收到答复，解析并返回呼叫者。
让我们仔细研究这些方法的参数并返回值。
这些方法中的大多数具有与相应命令相同的参数。以下是参数类型的列表：
| 参数类型 | 解释 | 例子 | 笔记 |
|---|---|---|---|
| StringView | 字符串类型的参数。通常用于键，值，成员名称，字段名称等 | bool redis :: hset（const StringView＆key，const StringView＆field，const StringView＆val） | 请参阅StringView部分以获取StringView上的详细信息 |
| 漫长 | 整数类型的参数。通常用于索引（例如列表命令）或整数 | void ltrim（const StringView＆Key，漫长的开始，长时间长时间） 长decorby（const stringview＆键，长长降低） | |
| 双倍的 | 浮点类型的参数。通常用于得分（例如排序命令）或浮点类型的数量 | double cormbyfloat（const StringView＆键，双重增量） | |
| STD :: Chrono ::持续时间 std :: chrono :: time_point | 时间相关参数 | Bool Exprey（const StringView＆key，const std :: chrono :: seconds＆timeout） Bool Expireat（const StringView＆key，const std :: chrono :: time_point <std :: chrono :: system_clock，std :: chrono :: chrono :: seconds>＆tp） | |
| STD :: PAIR <StringView，StringView> | 用于Redis Hash（字段，值）对 | bool hset（const StringView＆key，const std :: Pair <StringView，StringView>＆item） | |
| std ::配对<double，double> | 用于Redis Geo（经度，纬度）对 | OptionAllonglong Georadius（const StringView＆key，const std :: pair <double，double>＆location，double radius，geounit单元，const stringview＆destinate，bool store_dist，long long Count） | |
| 一对迭代器 | 使用一对迭代器指定一系列输入，以便我们可以将数据传递到STL容器中 | 模板<输入输入> 长长的del（输入第一，输入最后） | 抛出一个例外，如果是空范围，则首先==最后 |
| std :: initializer_list <t> | 使用初始化列表来指定一批输入 | 模板<typename t> Long long del（std :: prinitizer_list <t> il） | |
| 一些选项 | 某些命令的选项 | updateType ，模板<typename t>类有限制的Interval | 有关详细信息，请参见Command_options.h |
STD :: String_view是仅阅读字符串参数类型的不错选择。但是，仅在C ++ 17标准中引入std::string_view ，因此，如果您使用-std=c++11构建Redis -Plus -Plus （即通过指定-DREDIS_PLUS_PLUS_CXX_STANDARD=11使用CMAKE命令）或-std=c++14标准，则std::string_view StringView您可以使用-std=c++17标准（即默认行为）构建Redis-Plus-plus ，该标准将提供std::string_view intely。然后，将StringView实现忽略了，将其忽略到std::string_view 。这是在redis-plus-plus库中完成的： using StringView = std::string_view 。
由于std::string和C-Style String到StringView的转换，您只需将std::string或C-Style String传递到需要StringView参数的方法即可。
// bool Redis::hset(const StringView &key, const StringView &field, const StringView &val)
// Pass c-style string to StringView.
redis.hset( " key " , " field " , " value " );
// Pass std::string to StringView.
std::string key = " key " ;
std::string field = " field " ;
std::string val = " val " ;
redis.hset(key, field, val);
// Mix std::string and c-style string.
redis.hset(key, field, " value " );REDIS协议定义了5种答复：
long long 。而且这些答复可能是无效的。例如，当您尝试GET不存在的键的值时，Redis返回一个无块字符串回复。
如上所述，将答复解析为这些方法的返回值。以下是返回类型的列表：
| 返回类型 | 解释 | 例子 | 笔记 |
|---|---|---|---|
| 空白 | 状态答复应始终返回“确定”字符串 | 重命名， setEx | |
| std :: string | 状态答复并非总是返回“确定”，然后散装字符串回复 | ping ，信息 | |
| 布尔 | 整数答复总是返回0或1 | 到期， HSET | 有关布尔返回值的含义，请参见布尔回报值部分 |
| 漫长 | 整数答复并非总是返回0或1 | del ，附加 | |
| 双倍的 | 代表双重的散装字符串答复 | Zincrby的MercbyFloat | |
| std ::配对 | 数组与2个元素回复。 std::pair返回值始终是2个元素的数组 | blpop | |
| STD ::元组 | 数组的固定长度回复，并具有2个以上的元素。由于返回的数组的长度是固定的，因此我们将数组返回为std::tuple | BZPOPMAX | |
| 输出迭代器 | 一般数组以非固定/动态长度回复。我们使用类似STL的接口返回此类数组回复，以便您可以轻松地将返回值插入STL容器中 | MGE ， Lrange | 另外，有时输出迭代器的类型决定使用命令发送哪些选项。有关详细信息，请参见示例部分 |
| 可选<t> | 对于可能为null的T型的任何答复 | 获取， LPOP ， BLPOP ， BZPOPMAX | 有关Optional<T>的详细信息，请参见可选部分 |
| 变体<args ...> | 对于可能是服务不同类型的答复 | 内存统计 | 注意：到目前为止，只有在用C ++ 17标准编制Redis-Plus-Plus时才支持这种类型。通常与通用命令接口一起使用。有关Variant<Args...>的详细信息，请参见变体部分。 |
| STL容器 | 一般数组回复 | config get | 输出迭代器和STL容器均用于数组回复。不同之处在于， STL容器通常与通用命令接口一起使用。例如，请参见STL容器部分 |
某些方法的返回类型，例如EXPIRE ， HSET ，是bool 。如果该方法返回false ，则不意味着Redis无法将命令发送到REDIS服务器。相反，这意味着Redis服务器返回整数回复，并且答复的值为0 。因此，如果该方法返回true ，则意味着redis服务器返回整数答复，并且答复的值为1 。您可以查看REDIS命令手册的0和1代表。
例如，当我们将EXPIRE命令发送到redis服务器时，如果设置了超时，它将返回1 ，如果键不存在，则返回0 。因此，如果设置了超时， Redis::expire返回true ，如果不存在键， Redis::expire返回false 。
因此，切勿使用返回值检查命令是否已成功发送到Redis服务器。相反，如果Redis未能将命令发送到服务器，则会引发类型Error的例外。有关异常的详细信息，请参见异常部分。
如果Redis可能返回null回复，则STD ::可选的返回类型是一个不错的选择。但是，C ++ 17标准中引入了std::optional ，并且使用-std=c++11标准构建Redis -Plus -Plus （即通过指定-DREDIS_PLUS_PLUS_CXX_STANDARD=11使用CMake命令），我们实现了我们自己的简单版本，IE template Optional<T> 。取而代之的是，如果您使用-std=c++17标准（即默认行为）构建Redis-Plus-Plus ，则可以使用std::optional ，并且我们有一个别名： template <typename T> using Optional = std::optional<T> 。
以GET和MGET命令为例：
// Or just: auto val = redis.get("key");
Optional<std::string> val = redis.get( " key " );
// Optional<T> has a conversion to bool.
// If it's NOT a null Optional<T> object, it's converted to true.
// Otherwise, it's converted to false.
if (val) {
// Key exists. Dereference val to get the string result.
std::cout << *val << std::endl;
} else {
// Redis server returns a NULL Bulk String Reply.
// It's invalid to dereference a null Optional<T> object.
std::cout << " key doesn't exist. " << std::endl;
}
std::vector<Optional<std::string>> values;
redis.mget({ " key1 " , " key2 " , " key3 " }, std::back_inserter(values));
for ( const auto &val : values) {
if (val) {
// Key exist, process the value.
}
}我们还为一些常用的Optional<T>提供了一些类型：
using OptionalString = Optional<std::string>;
using OptionalLongLong = Optional< long long >;
using OptionalDouble = Optional< double >;
using OptionalStringPair = Optional<std::pair<std::string, std::string>>;如果答复可能是不同的类型，则STD ::变体是返回类型的一个不错选择。例如， MEMORY STATS命令返回一个数组回复，实际上是键值对配置的映射：
127.0.0.1: 6379> memory stats
1) " peak.allocated "
2) (integer) 4471104
...
17) " db.0 "
18) 1) " overhead.hashtable.main "
2) (integer) 104
3) " overhead.hashtable.expires "
4) (integer) 32
...
27) " dataset.percentage "
28) " 9.70208740234375 "
...但是，如您所见，结果的值部分可能是类型长的长度（键： peak.Salted ），double（键： dataset.percentage ）甚至地图（键： db.0 ）。因此，您不能简单地将结果解析为std::unordered_map<std::string, long long>或std::unordered_map<std::string, double> 。解决方法是将结果解析为tuple ，但是，该元组解决方案丑陋且容易出错。检查此问题以获取细节。
在这种情况下，如果您构建使用C ++ 17标准的Redis-Plus-Plus构建std::variant -Plus，则Variant是非常有帮助的。您可以将结果解析为std::unordered_map<std::string, Variant<double, long long, std::unordered_map<std::string, long long>>> 。
using Var = Variant< double , long long , std::unordered_map<std::string, long long >>;
auto r = Redis( " tcp://127.0.0.1 " );
auto v = r.command<std::unordered_map<std::string, Var>>( " memory " , " stats " );对Variant支持有一些限制：
Variant的类型参数，不能具有重复的项目，例如Variant<double, long long, double>不起作用。std::string之前放置double 。因为double答复实际上是字符串答复，并且在解析变体时，我们试图将答复解析为第一个匹配的类型，并用从左到右的类型参数指定。因此，如果在std::string之后放置double ，即在std::string的右侧放置，则答复将始终分解为std::string 。还要检查通用命令部分，以获取有关通用命令接口的更多示例。
使用通用命令接口时，您还可以将其解析为输出迭代器，而是可以将其解析为STL容器。
auto r = Redis( " tcp://127.0.0.1 " );
auto v = r.command<std::unordered_map<std::string, std::string>>( " config " , " get " , " * " );还要检查通用命令部分，以获取有关通用命令接口的更多示例。
让我们看看一些有关如何将命令发送到Redis服务器的示例。
// ***** Parameters of StringView type *****
// Implicitly construct StringView with c-style string.
redis.set( " key " , " value " );
// Implicitly construct StringView with std::string.
std::string key ( " key " );
std::string val ( " value " );
redis.set(key, val);
// Explicitly pass StringView as parameter.
std::vector< char > large_data;
// Avoid copying.
redis.set( " key " , StringView(large_data.data(), large_data.size()));
// ***** Parameters of long long type *****
// For index.
redis.bitcount(key, 1 , 3 );
// For number.
redis.incrby( " num " , 100 );
// ***** Parameters of double type *****
// For score.
redis.zadd( " zset " , " m1 " , 2.5 );
redis.zadd( " zset " , " m2 " , 3.5 );
redis.zadd( " zset " , " m3 " , 5 );
// For (longitude, latitude).
redis.geoadd( " geo " , std::make_tuple( " member " , 13.5 , 15.6 ));
// ***** Time-related parameters *****
using namespace std ::chrono ;
redis.expire(key, seconds( 1000 ));
auto tp = time_point_cast<seconds>(system_clock::now() + seconds( 100 ));
redis.expireat(key, tp);
// ***** Some options for commands *****
if (redis.set(key, " value " , milliseconds( 100 ), UpdateType::NOT_EXIST)) {
std::cout << " set OK " << std::endl;
}
redis.linsert( " list " , InsertPosition::BEFORE, " pivot " , " val " );
std::vector<std::string> res;
// (-inf, inf)
redis.zrangebyscore( " zset " , UnboundedInterval< double >{}, std::back_inserter(res));
// [3, 6]
redis.zrangebyscore( " zset " ,
BoundedInterval< double >( 3 , 6 , BoundType::CLOSED),
std::back_inserter (res));
// (3, 6]
redis.zrangebyscore( " zset " ,
BoundedInterval< double >( 3 , 6 , BoundType::LEFT_OPEN),
std::back_inserter (res));
// (3, 6)
redis.zrangebyscore( " zset " ,
BoundedInterval< double >( 3 , 6 , BoundType::OPEN),
std::back_inserter (res));
// [3, 6)
redis.zrangebyscore( " zset " ,
BoundedInterval< double >( 3 , 6 , BoundType::RIGHT_OPEN),
std::back_inserter (res));
// [3, +inf)
redis.zrangebyscore( " zset " ,
LeftBoundedInterval< double >( 3 , BoundType::RIGHT_OPEN),
std::back_inserter (res));
// (3, +inf)
redis.zrangebyscore( " zset " ,
LeftBoundedInterval< double >( 3 , BoundType::OPEN),
std::back_inserter (res));
// (-inf, 6]
redis.zrangebyscore( " zset " ,
RightBoundedInterval< double >( 6 , BoundType::LEFT_OPEN),
std::back_inserter (res));
// (-inf, 6)
redis.zrangebyscore( " zset " ,
RightBoundedInterval< double >( 6 , BoundType::OPEN),
std::back_inserter (res));
// ***** Pair of iterators *****
std::vector<std::pair<std::string, std::string>> kvs = {{ " k1 " , " v1 " }, { " k2 " , " v2 " }, { " k3 " , " v3 " }};
redis.mset(kvs.begin(), kvs.end());
std::unordered_map<std::string, std::string> kv_map = {{ " k1 " , " v1 " }, { " k2 " , " v2 " }, { " k3 " , " v3 " }};
redis.mset(kv_map.begin(), kv_map.end());
std::unordered_map<std::string, std::string> str_map = {{ " f1 " , " v1 " }, { " f2 " , " v2 " }, { " f3 " , " v3 " }};
redis.hmset( " hash " , str_map.begin(), str_map.end());
std::unordered_map<std::string, double > score_map = {{ " m1 " , 20 }, { " m2 " , 12.5 }, { " m3 " , 3.14 }};
redis.zadd( " zset " , score_map.begin(), score_map.end());
std::vector<std::string> keys = { " k1 " , " k2 " , " k3 " };
redis.del(keys.begin(), keys.end());
// ***** Parameters of initializer_list type *****
redis.mset({
std::make_pair ( " k1 " , " v1 " ),
std::make_pair ( " k2 " , " v2 " ),
std::make_pair ( " k3 " , " v3 " )
});
redis.hmset( " hash " ,
{
std::make_pair ( " f1 " , " v1 " ),
std::make_pair ( " f2 " , " v2 " ),
std::make_pair ( " f3 " , " v3 " )
});
redis.zadd( " zset " ,
{
std::make_pair ( " m1 " , 20.0 ),
std::make_pair ( " m2 " , 34.5 ),
std::make_pair ( " m3 " , 23.4 )
});
redis.del({ " k1 " , " k2 " , " k3 " }); // ***** Return void *****
redis.save();
// ***** Return std::string *****
auto info = redis.info();
// ***** Return bool *****
if (!redis.expire( " nonexistent " , std::chrono::seconds( 100 ))) {
std::cerr << " key doesn't exist " << std::endl;
}
if (redis.setnx( " key " , " val " )) {
std::cout << " set OK " << std::endl;
}
// ***** Return long long *****
auto len = redis.strlen( " key " );
auto num = redis.del({ " a " , " b " , " c " });
num = redis.incr( " a " );
// ***** Return double *****
auto real = redis.incrbyfloat( " b " , 23.4 );
real = redis.hincrbyfloat( " c " , " f " , 34.5 );
// ***** Return Optional<std::string>, i.e. OptionalString *****
auto os = redis.get( " kk " );
if (os) {
std::cout << *os << std::endl;
} else {
std::cerr << " key doesn't exist " << std::endl;
}
os = redis.spop( " set " );
if (os) {
std::cout << *os << std::endl;
} else {
std::cerr << " set is empty " << std::endl;
}
// ***** Return Optional<long long>, i.e. OptionalLongLong *****
auto oll = redis.zrank( " zset " , " mem " );
if (oll) {
std::cout << " rank is " << *oll << std::endl;
} else {
std::cerr << " member doesn't exist " << std::endl;
}
// ***** Return Optional<double>, i.e. OptionalDouble *****
auto ob = redis.zscore( " zset " , " m1 " );
if (ob) {
std::cout << " score is " << *ob << std::endl;
} else {
std::cerr << " member doesn't exist " << std::endl;
}
// ***** Return Optional<pair<string, string>> *****
auto op = redis.blpop({ " list1 " , " list2 " }, std::chrono::seconds( 2 ));
if (op) {
std::cout << " key is " << op-> first << " , value is " << op-> second << std::endl;
} else {
std::cerr << " timeout " << std::endl;
}
// ***** Output iterators *****
std::vector<OptionalString> os_vec;
redis.mget({ " k1 " , " k2 " , " k3 " }, std::back_inserter(os_vec));
std::vector<std::string> s_vec;
redis.lrange( " list " , 0 , - 1 , std::back_inserter(s_vec));
std::unordered_map<std::string, std::string> hash;
redis.hgetall( " hash " , std::inserter(hash, hash.end()));
// You can also save the result in a vecotr of string pair.
std::vector<std::pair<std::string, std::string>> hash_vec;
redis.hgetall( " hash " , std::back_inserter(hash_vec));
std::unordered_set<std::string> str_set;
redis.smembers( " s1 " , std::inserter(str_set, str_set.end()));
// You can also save the result in a vecotr of string.
s_vec.clear();
redis.smembers( " s1 " , std::back_inserter(s_vec));sw::redis::Cursor cursor = 0 ;
auto pattern = " *pattern* " ;
auto count = 5 ;
std::unordered_set<std::string> keys;
while ( true ) {
cursor = redis. scan (cursor, pattern, count, std::inserter (keys, keys. begin ()));
// Default pattern is "*", and default count is 10
// cursor = redis.scan(cursor, std::inserter(keys, keys.begin()));
if (cursor == 0 ) {
break ;
}
}有时，输出迭代器的类型决定使用命令发送哪些选项。
// If the output iterator is an iterator of a container of string,
// we send *ZRANGE* command without the *WITHSCORES* option.
std::vector<std::string> members;
redis.zrange( " list " , 0 , - 1 , std::back_inserter(members));
// If it's an iterator of a container of a <string, double> pair,
// we send *ZRANGE* command with *WITHSCORES* option.
std::vector<std::pair<std::string, double >> res_with_score;
redis.zrange( " list " , 0 , - 1 , std::back_inserter(res_with_score));
// The above examples also apply to other command with the *WITHSCORES* options,
// e.g. *ZRANGEBYSCORE*, *ZREVRANGE*, *ZREVRANGEBYSCORE*.
// Another example is the *GEORADIUS* command.
// Only get members.
members.clear();
redis.georadius( " geo " ,
std::make_pair ( 10.1 , 11.1 ),
100,
GeoUnit::KM,
10,
true,
std::back_inserter(members));
// If the iterator is an iterator of a container of tuple<string, double>,
// we send the *GEORADIUS* command with *WITHDIST* option.
std::vector<std::tuple<std::string, double >> mem_with_dist;
redis.georadius( " geo " ,
std::make_pair ( 10.1 , 11.1 ),
100,
GeoUnit::KM,
10,
true,
std::back_inserter(mem_with_dist));
// If the iterator is an iterator of a container of tuple<string, double, string>,
// we send the *GEORADIUS* command with *WITHDIST* and *WITHHASH* options.
std::vector<std::tuple<std::string, double , std::string>> mem_with_dist_hash;
redis.georadius( " geo " ,
std::make_pair ( 10.1 , 11.1 ),
100,
GeoUnit::KM,
10,
true,
std::back_inserter(mem_with_dist_hash));
// If the iterator is an iterator of a container of
// tuple<string, string, pair<double, double>, double>,
// we send the *GEORADIUS* command with *WITHHASH*, *WITHCOORD* and *WITHDIST* options.
std::vector<std::tuple<std::string, double , std::string>> mem_with_hash_coord_dist;
redis.georadius( " geo " ,
std::make_pair ( 10.1 , 11.1 ),
100,
GeoUnit::KM,
10,
true,
std::back_inserter(mem_with_hash_coord_dist));请参阅redis.h获取Doxygen样式的API参考和示例，并查看其他示例的测试。
Redis引发异常，如果它收到错误回复或发生错误的事情，例如无法创建与服务器的连接，或者与服务器的连接断开。从Error类得出的所有异常。有关详细信息，请参见错误。
Error ：通用错误。它源自std::exception ，也是其他例外的基类。IoError ：连接有一些IO错误。TimeoutError ：读取或写操作的时间已计时。这是派生的IoError类。ClosedError ：REDIS服务器关闭了连接。ProtoError ：命令或答复无效，我们无法使用REDIS协议进行处理。OomError ： HIRDIS库遇到了一个遗忘的错误。ReplyError ：Redis Server返回了错误回复，例如，我们尝试在Redis Hash上调用redis::lrange 。WatchError ：观看键已被修改。有关详细信息，请参见观看部分。注意： Null答复不被视为例外。例如，如果我们尝试GET不存在的密钥，我们将获得一个空的散装字符串回复。我们没有抛出异常，而是将null回复返回为null Optional<T>对象。另请参见可选部分。
通常，当发生例外时，您无需创建Redis对象。这是例外的安全，您可以重复使用Redis对象。即使与Redis服务器的连接断开，也会引发一些IoError 。下次使用Redis对象发送命令时，它将尝试自动重新连接到redis服务器。此规则也适用于RedisCluster 。但是，如果Pipeline ， Transcation和Subscriber抛出异常，则需要销毁对象，并创建一个新的对象。有关详细信息，请参见相应的文档。
以下是如何捕获以下例外的一个示例：
try {
redis. set ( " key " , " value " );
// Wrong type error
redis. lpush ( " key " , { " a " , " b " , " c " });
} catch ( const ReplyError &err) {
// WRONGTYPE Operation against a key holding the wrong kind of value
cout << err. what () << endl;
} catch ( const TimeoutError &err) {
// reading or writing timeout
} catch ( const ClosedError &err) {
// the connection has been closed.
} catch ( const IoError &err) {
// there's an IO error on the connection.
} catch ( const Error &err) {
// other errors
}Redis命令太多了，我们还没有实现所有命令。但是，您可以使用通用Redis::command方法将任何命令发送到redis。与其他客户端库不同， Redis::command不使用格式字符串将命令参数组合到命令字符串中。相反，您可以将StringView类型或算术类型的命令参数直接传递为Redis::command的参数。由于我们不使用格式字符串的原因，请参阅此讨论。
auto redis = Redis( " tcp://127.0.0.1 " );
// Redis class doesn't have built-in *CLIENT SETNAME* method.
// However, you can use Redis::command to send the command manually.
redis.command< void >( " client " , " setname " , " name " );
auto val = redis.command<OptionalString>( " client " , " getname " );
if (val) {
std::cout << *val << std::endl;
}
// NOTE: the following code is for example only. In fact, Redis has built-in
// methods for the following commands.
// Arguments of the command can be strings.
// NOTE: for SET command, the return value is NOT always void, I'll explain latter.
redis.command< void >( " set " , " key " , " 100 " );
// Arguments of the command can be a combination of strings and integers.
auto num = redis.command< long long >( " incrby " , " key " , 1 );
// Argument can also be double.
auto real = redis.command< double >( " incrbyfloat " , " key " , 2.3 );
// Even the key of the command can be of arithmetic type.
redis.command< void >( " set " , 100 , " value " );
val = redis.command<OptionalString>( " get " , 100 );
// If the command returns an array of elements.
std::vector<OptionalString> result;
redis.command( " mget " , " k1 " , " k2 " , " k3 " , std::back_inserter(result));
// Or just parse it into a vector.
result = redis.command<std::vector<OptionalString>>( " mget " , " k1 " , " k2 " , " k3 " );
// Arguments of the command can be a range of strings.
auto set_cmd_strs = { " set " , " key " , " value " };
redis.command< void >(set_cmd_strs.begin(), set_cmd_strs.end());
auto get_cmd_strs = { " get " , " key " };
val = redis.command<OptionalString>(get_cmd_strs.begin(), get_cmd_strs.end());
// If it returns an array of elements.
result.clear();
auto mget_cmd_strs = { " mget " , " key1 " , " key2 " };
redis.command(mget_cmd_strs.begin(), mget_cmd_strs.end(), std::back_inserter(result));注意：某些redis命令的名称由两个字符串组成，例如客户端setName 。在这种情况下，您需要将这两个字符串作为Redis::command的两个参数。
// This is GOOD.
redis.command< void >( " client " , " setname " , " name " );
// This is BAD, and will fail to send command to Redis server.
// redis.command<void>("client setname", "name");正如我在评论中提到的那样， SET命令并不总是返回void 。因为如果您尝试使用NX或XX选项设置（键，值）对，则可能会失败，Redis将返回null回复。 Besides the SET command, there're other commands whose return value is NOT a fixed type, you need to parse it by yourself. For example, Redis::set method rewrite the reply of SET command, and make it return bool type, ie if no NX or XX option specified, Redis server will always return an "OK" string, and Redis::set returns true ; if NX or XX specified, and Redis server returns a NULL REPLY , Redis::set returns false .
So Redis class also has other overloaded command methods, these methods return a ReplyUPtr , ie std::unique_ptr<redisReply, ReplyDeleter> , object. Normally you don't need to parse it manually. Instead, you only need to pass the reply to template <typename T> T reply::parse(redisReply &) to get a value of type T . Check the Return Type section for valid T types. If the command returns an array of elements, besides calling reply::parse to parse the reply to an STL container, you can also call template <typename Output> reply::to_array(redisReply &reply, Output output) to parse the result into an array or STL container with an output iterator.
Let's rewrite the above examples:
auto redis = Redis( " tcp://127.0.0.1 " );
redis.command( " client " , " setname " , " name " );
auto r = redis.command( " client " , " getname " );
assert (r);
// If the command returns a single element,
// use `reply::parse<T>(redisReply&)` to parse it.
auto val = reply::parse<OptionalString>(*r);
if (val) {
std::cout << *val << std::endl;
}
// Arguments of the command can be strings.
redis.command( " set " , " key " , " 100 " );
// Arguments of the command can be a combination of strings and integers.
r = redis.command( " incrby " , " key " , 1 );
auto num = reply::parse< long long >(*r);
// Argument can also be double.
r = redis.command( " incrbyfloat " , " key " , 2.3 );
auto real = reply::parse< double >(*r);
// Even the key of the command can be of arithmetic type.
redis.command( " set " , 100 , " value " );
r = redis.command( " get " , 100 );
val = reply::parse<OptionalString>(*r);
// If the command returns an array of elements.
r = redis.command( " mget " , " k1 " , " k2 " , " k3 " );
// Use `reply::to_array(redisReply&, OutputIterator)` to parse the result into an STL container.
std::vector<OptionalString> result;
reply::to_array (*r, std::back_inserter(result));
// Or just call `reply::parse` to parse it into vector.
result = reply::parse<std::vector<OptionalString>>(*r);
// Arguments of the command can be a range of strings.
auto get_cmd_strs = { " get " , " key " };
r = redis.command(get_cmd_strs.begin(), get_cmd_strs.end());
val = reply::parse<OptionalString>(*r);
// If it returns an array of elements.
result.clear();
auto mget_cmd_strs = { " mget " , " key1 " , " key2 " };
r = redis.command(mget_cmd_strs.begin(), mget_cmd_strs.end());
reply::to_array (*r, std::back_inserter(result)); In fact, there's one more Redis::command method:
template < typename Cmd, typename ...Args>
auto command (Cmd cmd, Args &&...args)
-> typename std::enable_if<!std::is_convertible<Cmd, StringView>::value, ReplyUPtr>::type;However, this method exposes some implementation details, and is only for internal use. You should NOT use this method.
You can use Redis::publish to publish messages to channels. Redis randomly picks a connection from the underlying connection pool, and publishes message with that connection. So you might publish two messages with two different connections.
When you subscribe to a channel with a connection, all messages published to the channel are sent back to that connection. So there's NO Redis::subscribe method. Instead, you can call Redis::subscriber to create a Subscriber and the Subscriber maintains a connection to Redis. The underlying connection is a new connection, NOT picked from the connection pool. This new connection has the same ConnectionOptions as the Redis object.
If you want to have different connection options, eg ConnectionOptions::socket_timeout , for different channels, you should create Redis objects with different connection options, then you can create Subscriber objects with these Redis objects. Check this issue for a use case.
ConnectionOptions opts1;
opts1.host = " 127.0.0.1 " ;
opts1.port = 6379 ;
opts1.socket_timeout = std::chrono::milliseconds( 100 );
auto redis1 = Redis(opts1);
// sub1's socket_timeout is 100ms.
auto sub1 = redis1.subscriber();
ConnectionOptions opts2;
opts2.host = " 127.0.0.1 " ;
opts2.port = 6379 ;
opts2.socket_timeout = std::chrono::milliseconds( 300 );
auto redis2 = Redis(opts2);
// sub2's socket_timeout is 300ms.
auto sub2 = redis2.subscriber(); NOTE : Although the above code creates two Redis objects, it has no performance penalty. Because Redis object creates connections lazily, ie no connection will be created until we send some command with Redis object, and the connection is created only when we call Redis::subscriber to create Subscriber object.
With Subscriber , you can call Subscriber::subscribe , Subscriber::unsubscribe , Subscriber::psubscribe and Subscriber::punsubscribe to send SUBSCRIBE , UNSUBSCRIBE , PSUBSCRIBE and PUNSUBSCRIBE commands to Redis.
Subscriber is NOT thread-safe. If you want to call its member functions in multi-thread environment, you need to synchronize between threads manually.
If any of the Subscriber 's method throws an exception other than ReplyError or TimeoutError , you CANNOT use it any more. Instead, you have to destroy the Subscriber object, and create a new one.
There are 6 kinds of messages:
We call messages of SUBSCRIBE , UNSUBSCRIBE , PSUBSCRIBE and PUNSUBSCRIBE types as META MESSAGE s.
In order to process these messages, you can set callback functions on Subscriber :
Subscriber::on_message(MsgCallback) : set callback function for messages of MESSAGE type, and the callback interface is: void (std::string channel, std::string msg) .Subscriber::on_pmessage(PatternMsgCallback) : set the callback function for messages of PMESSAGE type, and the callback interface is: void (std::string pattern, std::string channel, std::string msg) .Subscriber::on_meta(MetaCallback) : set callback function for messages of META MESSAGE type, and the callback interface is: void (Subscriber::MsgType type, OptionalString channel, long long num) . type is an enum, it can be one of the following enum: Subscriber::MsgType::SUBSCRIBE , Subscriber::MsgType::UNSUBSCRIBE , Subscriber::MsgType::PSUBSCRIBE , Subscriber::MsgType::PUNSUBSCRIBE , Subscriber::MsgType::MESSAGE , and Subscriber::MsgType::PMESSAGE . If you haven't subscribe/psubscribe to any channel/pattern, and try to unsubscribe/punsubscribe without any parameter, ie unsubscribe/punsubscribe all channels/patterns, channel will be null. So the second parameter of meta callback is of type OptionalString . All these callback interfaces pass std::string by value, and you can take their ownership (ie std::move ) safely.
You can call Subscriber::consume to consume messages published to channels/patterns that the Subscriber has been subscribed.
Subscriber::consume waits for message from the underlying connection. If the ConnectionOptions::socket_timeout is reached, and there's no message sent to this connection, Subscriber::consume throws a TimeoutError exception. If ConnectionOptions::socket_timeout is 0ms , Subscriber::consume blocks until it receives a message.
After receiving the message, Subscriber::consume calls the callback function to process the message based on message type. However, if you don't set callback for a specific kind of message, Subscriber::consume will consume the received message and discard it, ie Subscriber::consume returns without running the callback.
The following example is a common pattern for using Subscriber :
// Create a Subscriber.
auto sub = redis.subscriber();
// Set callback functions.
sub.on_message([](std::string channel, std::string msg) {
// Process message of MESSAGE type.
});
sub.on_pmessage([](std::string pattern, std::string channel, std::string msg) {
// Process message of PMESSAGE type.
});
sub.on_meta([](Subscriber::MsgType type, OptionalString channel, long long num) {
// Process message of META type.
});
// Subscribe to channels and patterns.
sub.subscribe( " channel1 " );
sub.subscribe({ " channel2 " , " channel3 " });
sub.psubscribe( " pattern1* " );
// Consume messages in a loop.
while ( true ) {
try {
sub. consume ();
} catch ( const Error &err) {
// Handle exceptions.
}
} If ConnectionOptions::socket_timeout is set, you might get TimeoutError exception before receiving a message:
while ( true ) {
try {
sub. consume ();
} catch ( const TimeoutError &e) {
// Try again.
continue ;
} catch ( const Error &err) {
// Handle other exceptions.
}
}The above examples use lambda as callback. If you're not familiar with lambda, you can also set a free function as callback. Check this issue for detail.
Pipeline is used to reduce RTT (Round Trip Time), and speed up Redis queries. redis-plus-plus supports pipeline with the Pipeline class.
You can create a pipeline with Redis::pipeline method, which returns a Pipeline object.
ConnectionOptions connection_options;
ConnectionPoolOptions pool_options;
Redis redis (connection_options, pool_options);
auto pipe = redis.pipeline(); When creating a Pipeline object, by default, Redis::pipeline method creates a new connection to Redis server. This connection is NOT picked from the connection pool, but a newly created connection. This connection has the same ConnectionOptions as other connections in the connection pool. Pipeline object maintains the new connection, and all piped commands are sent through this connection.
NOTE : By default, creating a Pipeline object is NOT cheap, since it creates a new connection. So you'd better reuse the Pipeline object as much as possible. Check this to see how to create a Pipeline object without creating a new connection.
You can send Redis commands through the Pipeline object. Just like the Redis class, Pipeline has one or more (overloaded) methods for each Redis command. However, you CANNOT get the replies until you call Pipeline::exec . So these methods do NOT return the reply, instead they return the Pipeline object itself. And you can chain these methods calls.
pipe.set( " key " , " val " ).incr( " num " ).rpush( " list " , { 0 , 1 , 2 }).command( " hset " , " key " , " field " , " value " ); Once you finish sending commands to Redis, you can call Pipeline::exec to get replies of these commands. You can also chain Pipeline::exec with other commands.
pipe.set( " key " , " val " ).incr( " num " );
auto replies = pipe.exec();
// The same as:
replies = pipe.set( " key " , " val " ).incr( " num " ).exec(); In fact, these commands won't be sent to Redis, until you call Pipeline::exec . So Pipeline::exec does 2 work in order: send all piped commands, then get all replies from Redis.
Also you can call Pipeline::discard to discard those piped commands.
pipe.set( " key " , " val " ).incr( " num " );
pipe.discard(); Pipeline::exec returns a QueuedReplies object, which contains replies of all commands that have been sent to Redis. You can use QueuedReplies::get method to get and parse the ith reply. It has 3 overloads:
template <typename Result> Result get(std::size_t idx) : Return the ith reply as a return value, and you need to specify the return type as tempalte parameter.template <typename Output> void get(std::size_t idx, Output output) : If the reply is of type Array Reply , you can call this method to write the ith reply to an output iterator. Normally, compiler will deduce the type of the output iterator, and you don't need to specify the type parameter explicitly.redisReply& get(std::size_t idx) : If the reply is NOT a fixed type, call this method to get a reference to redisReply object. In this case, you need to call template <typename T> T reply::parse(redisReply &) to parse the reply manually.Check the Return Type section for details on the return types of the result.
auto replies = pipe.set( " key " , " val " ).incr( " num " ).lrange( " list " , 0 , - 1 ).exec();
auto set_cmd_result = replies.get< bool >( 0 );
auto incr_cmd_result = replies.get< long long >( 1 );
std::vector<std::string> list_cmd_result;
replies.get( 2 , std::back_inserter(list_cmd_result));If any of Pipeline 's method throws an exception other than ReplyError , the Pipeline object enters an invalid state. You CANNOT use it any more, but only destroy the object, and create a new one.
Pipeline is NOT thread-safe. If you want to call its member functions in multi-thread environment, you need to synchronize between threads manually.
YOU MUST CAREFULLY READ ALL WORDS IN THIS SECTION AND THE VERY IMPORTANT NOTES BEFORE USING THIS FEATURE!!!
In fact, you can also create a Pipeline object with a connection from the underlying connection pool, so that calling Redis::pipeline method can be much cheaper (since it doesn't need to create a new connection).
The prototype of Redis::pipeline is as follows: Pipeline pipeline(bool new_connection = true); . If new_connection is false, the Pipeline object will be created with a connection from the underlying pool.
ConnectionOptions connection_options;
ConnectionPoolOptions pool_options;
Redis redis (connection_options, pool_options);
// Create a Pipeline without creating a new connection.
auto pipe = redis.pipeline( false ); However, in this case, you MUST be very careful, otherwise, you might get bad performance or even dead lock. Because when you run command with Pipeline object, it will hold the connection until Pipeline::exec , Pipeline::discard or Pipeline 's destructor is called (the connection will also be released if any method of Pipeline throws Exception ). If the Pipeline object holds the connection for a long time, other Redis methods might not be able to get a connection from the underlying pool.
Check the following dead lock example:
// By defaul, create a `Redis` object with only ONE connection in pool.
// Also by default, the `ConnectionPoolOptions::wait_timeout` is 0ms,
// which means if the pool is empty, `Redis` method will be blocked until
// the pool is not empty.
Redis redis ( " tcp://127.0.0.1 " );
// Create a `Pipeline` with a connection in the underlying pool.
// In fact, the connection hasn't been fetched from the pool
// until some method of `Pipeline` has been called.
auto pipe = redis.pipeline( false );
// Now the `Pipeline` object fetches a connection from the pool.
pipe.set( " key1 " , " val " );
// `Pipeline` object still holds the connection until `Pipeline::exec`,
// `Pipeline::discard` or the destructor is called.
pipe.set( " key2 " , " val " );
// Try to send a command with `Redis` object.
// However, the pool is empty, since the `Pipeline` object still holds
// the connection, and this call will be blocked forever.
// DEAD LOCK!!!
redis.get( " key " );
// NEVER goes here.
pipe.exec();BEST PRACTICE :
When creating Pipeline without creating a new connection:
ConnectionPoolOptions::wait_timeout larger than 0ms (ie when pool is empty, never block forever).Pipeline 's methods.Pipeline methods and the Pipeline::exec in one statements.Pipeline related code in a block scope. ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
opts.socket_timeout = std::chrono::milliseconds( 50 );
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ;
// Always set `wait_timeout` larger than 0ms.
pool_opts.wait_timeout = std::chrono::milliseconds( 50 );
auto redis = Redis(opts, pool_opts);
{
// Better put `Pipeline` related code in a block scope.
auto pipe = redis. pipeline ( false );
pipe . set ( " key1 " , " val " );
// DON'T run slow operations here, since `Pipeline` object still holds
// the connection, other threads using this `Redis` object, might be blocked.
pipe . set ( " key2 " , " val " );
// When `Pipeline::exec` finishes, `Pipeline` releases the connection, and returns it to pool.
auto replies = pipe . exec ();
// This is even better, i.e. chain `Pipeline` methods with `Pipeline::exec`.
replies = pipe . set ( " key1 " , " val " ). set ( " key2 " , " val " ). exec ();
}
for ( auto i = 0 ; i < 10 ; ++i) {
// This operation, i.e. creating a `Pipeline` object with connection in pool, is cheap
auto pipe = redis. pipeline ( false );
// Fetch a connection from the underlying pool, and hold it.
pipe . set ( " key1 " , " val " ). set ( " key2 " , " val " );
// Although `Pipeline::exec` and `Pipeline::discard` haven't been called,
// when `Pipeline`'s destructor is called, the connection will also be
// returned to the pool.
}Transaction is used to make multiple commands runs atomically.
You can create a transaction with Redis::transaction method, which returns a Transaction object.
ConnectionOptions connection_options;
ConnectionPoolOptions pool_options;
Redis redis (connection_options, pool_options);
auto tx = redis.transaction(); As the Pipeline class, Transaction maintains a newly created connection to Redis. This connection has the same ConnectionOptions as the Redis object.
NOTE : Creating a Transaction object is NOT cheap, since it creates a new connection. So you'd better reuse the Transaction as much as possible. Check this to see how to create a Transaction object without creating a new connection.
Also you don't need to send MULTI command to Redis. Transaction will do that for you automatically.
Transaction shares most of implementation with Pipeline . It has the same interfaces as Pipeline . You can send commands as what you do with Pipeline object.
tx.set( " key " , " val " ).incr( " num " ).lpush( " list " , { 0 , 1 , 2 }).command( " hset " , " key " , " field " , " val " ); When you call Transaction::exec , you explicitly ask Redis to execute those queued commands, and return the replies. Otherwise, these commands won't be executed. Also, you can call Transaction::discard to discard the execution, ie no command will be executed. Both Transaction::exec and Transaction::discard can be chained with other commands.
auto replies = tx.set( " key " , " val " ).incr( " num " ).exec();
tx.set( " key " , " val " ).incr( " num " );
// Discard the transaction.
tx.discard();See Pipeline's Parse Replies section for how to parse the replies.
Normally, we always send multiple commnds in a transaction. In order to improve the performance, you can send these commands in a pipeline. You can create a piped transaction by passing true as parameter of Redis::transaction method.
// Create a piped transaction
auto tx = redis.transaction( true );With this piped transaction, all commands are sent to Redis in a pipeline.
If any of Transaction 's method throws an exception other than WatchError or ReplyError , the Transaction object enters an invalid state. You CANNOT use it any more, but only destroy the object and create a new one.
Transacation is NOT thread-safe. If you want to call its member functions in multi-thread environment, you need to synchronize between threads manually.
WATCH is used to provide a check-and-set(CAS) behavior to Redis transactions.
The WATCH command must be sent in the same connection as the transaction. And normally after the WATCH command, we also need to send some other commands to get data from Redis before executing the transaction. Take the following check-and-set case as an example:
WATCH key // watch a key
val = GET key // get value of the key
new_val = val + 1 // incr the value
MULTI // begin the transaction
SET key new_val // set value only if the value is NOT modified by others
EXEC // try to execute the transaction.
// if val has been modified, the transaction won't be executed.
However, with Transaction object, you CANNOT get the result of commands until the whole transaction has been finished. Instead, you need to create a Redis object from the Transaction object. The created Redis object shares the connection with Transaction object. With this created Redis object, you can send WATCH command and any other Redis commands to Redis server, and get the result immediately.
Let's see how to implement the above example with redis-plus-plus :
auto redis = Redis( " tcp://127.0.0.1 " );
// Create a transaction.
auto tx = redis.transaction();
// Create a Redis object from the Transaction object. Both objects share the same connection.
auto r = tx.redis();
// If the watched key has been modified by other clients, the transaction might fail.
// So we need to retry the transaction in a loop.
while ( true ) {
try {
// Watch a key.
r. watch ( " key " );
// Get the old value.
auto val = r. get ( " key " );
auto num = 0 ;
if (val) {
num = std::stoi (*val);
} // else use default value, i.e. 0.
// Incr value.
++num;
// Execute the transaction.
auto replies = tx. set ( " key " , std::to_string (num)). exec ();
// Transaction has been executed successfully. Check the result and break.
assert (replies. size () == 1 && replies. get < bool >( 0 ) == true );
break ;
} catch ( const WatchError &err) {
// Key has been modified by other clients, retry.
continue ;
} catch ( const Error &err) {
// Something bad happens, and the Transaction object is no longer valid.
throw ;
}
} NOTE : in the example above, we create Transaction object outside the while loop, in order to avoid creating new connection again and again.
NOTE : YOU MUST CAREFULLY READ ALL WORDS AND THE VERY IMPORTANT NOTES LINK IN THIS SECTION BEFORE USING THIS FEATURE!!!
In fact, you can also create a transaction object with a connection from the underlying connection pool, so that calling Redis::transaction method can be much cheaper (since it doesn't need to create a new connection).
The prototype of Redis::transaction is as follows: Transaction transaction(bool piped = false, bool new_connection = true); . If new_connection is false, the Transaction object will be created with a connection from the underlying pool.
ConnectionOptions connection_options;
ConnectionPoolOptions pool_options;
Redis redis (connection_options, pool_options);
// Create a Transaction without creating a new connection.
auto tx = redis.transaction( false , false );However, in this case, you MUST be very careful, otherwise, you might get bad performance or even dead lock. Please carefully check the similar pipeline's VERY IMPORTANT NOTES section, before you use it!
Besides those very important notes, there's another important note for Transaction :
Redis object created by Transaction::Redis , ie destroy it ASAP.Check the following example:
auto redis = Redis(opts, pool_opts);
// Create a `Transaction` object without creating a new connection.
auto tx = redis.Transaction( false , false );
// Create a `Redis`, and this `Redis` object shares the same connection with the `Transaction` object.
auto r = tx.redis();
// Other code here...
// Execute the transaction.
auto replies = tx.set( " key " , " val " ).exec();
// Although `Transaction::exec` has been called, the connection has not been returned to pool.
// Because the `Redis` object, i.e. `r`, still holds the connection.So the above watch example should be modified as follows:
auto redis = Redis(opts, pool_opts);
// If the watched key has been modified by other clients, the transaction might fail.
// So we need to retry the transaction in a loop.
while ( true ) {
try {
// Create a transaction without creating a new connection.
auto tx = redis. transaction ( false , false );
// Create a Redis object from the Transaction object. Both objects share the same connection.
auto r = tx. redis ();
// Watch a key.
r. watch ( " key " );
// Get the old value.
auto val = r. get ( " key " );
auto num = 0 ;
if (val) {
num = std::stoi (*val);
} // else use default value, i.e. 0.
// Incr value.
++num;
// Execute the transaction.
auto replies = tx. set ( " key " , std::to_string (num)). exec ();
// Transaction has been executed successfully. Check the result and break.
assert (replies. size () == 1 && replies. get < bool >( 0 ) == true );
break ;
} catch ( const WatchError &err) {
// Key has been modified by other clients, retry.
continue ;
} catch ( const Error &err) {
// Something bad happens, and the Transaction object is no longer valid.
throw ;
}
} NOTE : The difference is that we create the Transaction object in the while loop (it's cheap, since it doesn't need to create a new connection). When the Transaction object and the Redis object created by Transaction::redis have been destroyed, the connection will be return to pool.
redis-plus-plus supports Redis Cluster. You can use RedisCluster class to send commands to Redis Cluster. It has similar interfaces as Redis class.
By default, RedisCluster connects to all master nodes in the cluster. For each master node, it maintains a connection pool. If you want to read from slave nodes, you need to explicitly set an option (see below for reference).
You can initialize a RedisCluster instance with ConnectionOptions and ConnectionPoolOptions . You only need to set one master node's host & port in ConnectionOptions , and RedisCluster will get other nodes' info automatically (with the CLUSTER SLOTS command). For each master node, it creates a connection pool with the specified ConnectionPoolOptions . If ConnectionPoolOptions is not specified, RedisCluster maintains a single connection to every master node.
// Set a master node's host & port.
ConnectionOptions connection_options;
connection_options.host = " 127.0.0.1 " ; // Required.
connection_options.port = 7000 ; // Optional. The default port is 6379.
connection_options.password = " auth " ; // Optional. No password by default.
// Automatically get other nodes' info,
// and connect to every master node with a single connection.
RedisCluster cluster1 (connection_options);
ConnectionPoolOptions pool_options;
pool_options.size = 3 ;
// For each master node, maintains a connection pool of size 3.
RedisCluster cluster2 (connection_options, pool_options); You can also specify connection option with an URI. However, in this way, you can only use default ConnectionPoolOptions , ie pool of size 1, and CANNOT specify password.
// Specify a master node's host & port.
RedisCluster cluster3 ( " tcp://127.0.0.1:7000 " );
// Use default port, i.e. 6379.
RedisCluster cluster4 ( " tcp://127.0.0.1 " ); If you want to scale read by reading (possible stale) data from slave nodes, you can specifiy Role::SLAVE as the third parameter of RedisCluster 's constructor. In this case, redis-plus-plus will randomly pick a replica node for each master node of the cluster, and create a connection pool for the replica node.
RedisCluster cluster (connection_options, pool_options, Role::SLAVE);
auto val = cluster.get( " key " ); In this case, you can only send readonly commands to Redis Cluster. If you try to send a write command, eg set , hset , redis-plus-plus will throw an exception. Currently, redis-plus-plus doesn't handle this case, ie sending write command in Role::SLAVE mode, elegantly, and you might get some performance problem. So, NEVER send write command in Role::SLAVE mode. I'll fix this issue in the future.
NOTE : In Role::SLAVE mode, you don't need to manually send READONLY command to slave nodes. Instead, redis-plus-plus will send READONLY command to slave nodes automatically.
RedisCluster only works with tcp connection. It CANNOT connect to Unix Domain Socket. If you specify Unix Domain Socket in ConnectionOptions , it throws an exception.ConnectionOptions::db is ignored. As we mentioned above, RedisCluster 's interfaces are similar to Redis . It supports most of Redis ' interfaces, including the generic command interface (see Redis ' API Reference section for details), except the following:
PING , INFO . Since there's no key parameter, RedisCluster has no idea on to which node these commands should be sent. However there're 2 workarounds for this problem:
Redis object with that node's host and port, and use the Redis object to do the work.Redis RedisCluster::redis(const StringView &hash_tag) to create a Redis object with a hash-tag specifying the node. In this case, the returned Redis object creates a new connection to Redis server. NOTE : the returned Redis object, IS NOT THREAD SAFE! . Also, when using the returned Redis object, if it throws exception, you need to destroy it, and create a new one with the RedisCluster::redis method.Also you can use the hash tags to send multiple-key commands.
See the example section for details.
You can publish and subscribe messages with RedisCluster . The interfaces are exactly the same as Redis , ie use RedisCluster::publish to publish messages, and use RedisCluster::subscriber to create a subscriber to consume messages. See Publish/Subscribe section for details.
You can also create Pipeline and Transaction objects with RedisCluster , but the interfaces are different from Redis . Since all commands in the pipeline and transaction should be sent to a single node in a single connection, we need to tell RedisCluster with which node the pipeline or transaction should be created.
Instead of specifying the node's IP and port, RedisCluster 's pipeline and transaction interfaces allow you to specify the node with a hash tag . RedisCluster will calculate the slot number with the given hash tag , and create a pipeline or transaction with the node holding the slot.
Pipeline RedisCluster::pipeline ( const StringView &hash_tag, bool new_connection = true );
Transaction RedisCluster::transaction ( const StringView &hash_tag, bool piped = false , bool new_connection = true ); With the created Pipeline or Transaction object, you can send commands with keys located on the same node as the given hash_tag . See Examples section for an example.
NOTE : By default, Pipeline and Transaction will be created with a new connection. In order to avoid creating new connection, you can pass false as the last parameter. However, in this case, you MUST be very careful, otherwise, you might get bad performance or even dead lock. Please carefully check the related pipeline section before using this feature.
# include < sw/redis++/redis++.h >
using namespace sw ::redis ;
auto redis_cluster = RedisCluster( " tcp://127.0.0.1:7000 " );
redis_cluster.set( " key " , " value " );
auto val = redis_cluster.get( " key " );
if (val) {
std::cout << *val << std::endl;
}
// With hash-tag.
redis_cluster.set( " key{tag}1 " , " val1 " );
redis_cluster.set( " key{tag}2 " , " val2 " );
redis_cluster.set( " key{tag}3 " , " val3 " );
std::vector<OptionalString> hash_tag_res;
redis_cluster.mget({ " key{tag}1 " , " key{tag}2 " , " key{tag}3 " },
std::back_inserter (hash_tag_res));
redis_cluster.lpush( " list " , { " 1 " , " 2 " , " 3 " });
std::vector<std::string> list;
redis_cluster.lrange( " list " , 0 , - 1 , std::back_inserter(list));
// Pipeline.
auto pipe = redis_cluster.pipeline( " counter " );
auto replies = pipe.incr( " {counter}:1 " ).incr( " {counter}:2 " ).exec();
// Transaction.
auto tx = redis_cluster.transaction( " key " );
replies = tx.incr( " key " ).get( " key " ).exec();
// Create a Redis object with hash-tag.
// It connects to the Redis instance that holds the given key, i.e. hash-tag.
auto r = redis_cluster.redis( " hash-tag " );
// And send command without key parameter to the server.
r.command( " client " , " setname " , " connection-name " ); NOTE : By default, when you use RedisCluster::redis(const StringView &hash_tag, bool new_connection = true) to create a Redis object, instead of picking a connection from the underlying connection pool, it creates a new connection to the corresponding Redis server. So this is NOT a cheap operation, and you should try to reuse this newly created Redis object as much as possible. If you pass false as the second parameter, you can create a Redis object without creating a new connection. However, in this case, you should be very careful, otherwise, you might get bad performance or even dead lock. Please carefully check the related pipeline section before using this feature.
// This is BAD! It's very inefficient.
// NEVER DO IT!!!
// After sending PING command, the newly created Redis object will be destroied.
cluster.redis( " key " ).ping();
// Then it creates a connection to Redis, and closes the connection after sending the command.
cluster.redis( " key " ).command( " client " , " setname " , " hello " );
// Instead you should reuse the Redis object.
// This is GOOD!
auto redis = cluster.redis( " key " );
redis.ping();
redis.command( " client " , " setname " , " hello " );
// This is GOOD! Create `Redis` object without creating a new connection. Use it, and destroy it ASAP.
cluster.redis( " key " , false ).ping();RedisCluster maintains the newest slot-node mapping, and sends command directly to the right node. Normally it works as fast as Redis . If the cluster reshards, RedisCluster will follow the redirection, and it will finally update the slot-node mapping. It can correctly handle the following resharding cases:
redis-plus-plus is able to handle both MOVED and ASK redirections, so it's a complete Redis Cluster client.
If master is down, the cluster will promote one of its replicas to be the new master. redis-plus-plus can also handle this case:
Since redis-plus-plus 1.3.13, it also updates the slot-node mapping every ClusterOptions::slot_map_refresh_interval time interval (by default, it updates every 10 seconds).
Redis Sentinel provides high availability for Redis. If Redis master is down, Redis Sentinels will elect a new master from slaves, ie failover. Besides, Redis Sentinel can also act like a configuration provider for clients, and clients can query master or slave address from Redis Sentinel. So that if a failover occurs, clients can ask the new master address from Redis Sentinel.
redis-plus-plus supports getting Redis master or slave's IP and port from Redis Sentinel. In order to use this feature, you only need to initialize Redis object with Redis Sentinel info, which is composed with 3 parts: std::shared_ptr<Sentinel> , master name and role (master or slave).
Before using Redis Sentinel with redis-plus-plus , ensure that you have read Redis Sentinel's doc.
You can create a std::shared_ptr<Sentinel> object with SentinelOptions .
SentinelOptions sentinel_opts;
sentinel_opts.nodes = {{ " 127.0.0.1 " , 9000 },
{ " 127.0.0.1 " , 9001 },
{ " 127.0.0.1 " , 9002 }}; // Required. List of Redis Sentinel nodes.
// Optional. Timeout before we successfully connect to Redis Sentinel.
// By default, the timeout is 100ms.
sentinel_opts.connect_timeout = std::chrono::milliseconds( 200 );
// Optional. Timeout before we successfully send request to or receive response from Redis Sentinel.
// By default, the timeout is 100ms.
sentinel_opts.socket_timeout = std::chrono::milliseconds( 200 );
auto sentinel = std::make_shared<Sentinel>(sentinel_opts); SentinelOptions::connect_timeout and SentinelOptions::socket_timeout CANNOT be 0ms, ie no timeout and block forever. Otherwise, redis-plus-plus will throw an exception.
See SentinelOptions for more options.
Besides std::shared_ptr<Sentinel> and master name, you also need to specify a role. There are two roles: Role::MASTER , and Role::SLAVE .
With Role::MASTER , redis-plus-plus will always connect to current master instance, even if a failover occurs. Each time when redis-plus-plus needs to create a new connection to master, or a connection is broken, and it needs to reconnect to master, redis-plus-plus will ask master address from Redis Sentinel, and connects to current master. If a failover occurs, redis-plus-plus can automatically get the address of the new master, and refresh all connections in the underlying connection pool.
Similarly, with Role::SLAVE , redis-plus-plus will always connect to a slave instance. A master might have several slaves, redis-plus-plus will randomly pick one, and connect to it, ie all connections in the underlying connection pool, connect to the same slave instance (check this discussion on why redis-plus-plus not connect to all slaves). If the connection is broken, while this slave instance is still an alive slave, redis-plus-plus will reconnect to this slave. However, if this slave instance is down, or it has been promoted to be the master, redis-plus-plus will randomly connect to another slave. If there's no slave alive, it throws an exception.
When creating a Redis object with sentinel, besides the sentinel info, you should also provide ConnectionOptions and ConnectionPoolOptions . These two options are used to connect to Redis instance. ConnectionPoolOptions is optional, if not specified, it creates a single connection the instance.
ConnectionOptions connection_opts;
connection_opts.password = " auth " ; // Optional. No password by default.
connection_opts.connect_timeout = std::chrono::milliseconds( 100 ); // Required.
connection_opts.socket_timeout = std::chrono::milliseconds( 100 ); // Required.
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ; // Optional. The default size is 1.
auto redis = Redis(sentinel, " master_name " , Role::MASTER, connection_opts, pool_opts); You might have noticed that we didn't specify the host and port fields for ConnectionOptions . Because, Redis will get these info from Redis Sentinel. Also, in this case, ConnectionOptions::connect_timeout and ConnectionOptions::socket_timeout CANNOT be 0ms, otherwise, it throws an exception. So you always need to specify these two timeouts manually.
After creating the Redis object with sentinel, you can send commands with it, just like an ordinary Redis object.
If you want to write to master, and scale read with slaves. You can use the following pattern:
auto sentinel = std::make_shared<Sentinel>(sentinel_opts);
auto master = Redis(sentinel, " master_name " , Role::MASTER, connection_opts, pool_opts);
auto slave = Redis(sentinel, " master_name " , Role::SLAVE, connection_opts, pool_opts);
// Write to master.
master.set( " key " , " value " );
// Read from slave.
slave.get( " key " );Since Redis 5.0, it introduces a new data type: Redis Stream . redis-plus-plus has built-in methods for all stream commands except the XINFO command (of course, you can use the Generic Command Interface to send XINFO command).
However, the replies of some streams commands, ie XPENDING , XREAD , are complex. So I'll give some examples to show you how to work with these built-in methods.
auto redis = Redis( " tcp://127.0.0.1 " );
using Attrs = std::vector<std::pair<std::string, std::string>>;
// You can also use std::unordered_map, if you don't care the order of attributes:
// using Attrs = std::unordered_map<std::string, std::string>;
Attrs attrs = { { " f1 " , " v1 " }, { " f2 " , " v2 " } };
// Add an item into the stream. This method returns the auto generated id.
auto id = redis.xadd( " key " , " * " , attrs.begin(), attrs.end());
// Each item is assigned with an id: pair<id, Optional<attributes>>.
// NOTE: the attribute part might be nil reply, check [this issue](https://github.com/sewenew/redis-plus-plus/issues/283) for detail.
using Item = std::pair<std::string, Optional<Attrs>>;
using ItemStream = std::vector<Item>;
// If you don't care the order of items in the stream, you can also use unordered_map:
// using ItemStream = std::unordered_map<std::string, Attrs>;
// Read items from a stream, and return at most 10 items.
// You need to specify a key and an id (timestamp + offset).
std::unordered_map<std::string, ItemStream> result;
redis.xread( " key " , id, 10 , std::inserter(result, result.end()));
// Read from multiple streams. For each stream, you need to specify a key and an id.
std::unordered_map<std::string, std::string> keys = { { " key " , id}, { " another-key " , " 0-0 " } };
redis.xread(keys.begin(), keys.end(), 10 , std::inserter(result, result.end()));
// Block for at most 1 second if currently there's no data in the stream.
redis.xread( " key " , id, std::chrono::seconds( 1 ), 10 , std::inserter(result, result.end()));
// Block for multiple streams.
redis.xread(keys.begin(), keys.end(), std::chrono::seconds( 1 ), 10 , std::inserter(result, result.end()));
// Read items in a range:
ItemStream item_stream;
redis.xrange( " key " , " - " , " + " , std::back_inserter(item_stream));
// Trim the stream to a given number of items. After the operation, the stream length is NOT exactly
// 10. Instead, it might be much larger than 10.
// `XTRIM key MAXLEN 10`
redis.xtrim( " key " , 10 );
// In order to trim the stream to exactly 10 items, specify the third argument, i.e. approx, as false.
// `XTRIM key MAXLEN ~ 10`
redis.xtrim( " key " , 10 , false );
// Delete an item from the stream.
redis.xdel( " key " , id);
// Create a consumer group.
redis.xgroup_create( " key " , " group " , " $ " );
// If the stream doesn't exist, you can set the fourth argument, i.e. MKSTREAM, to be true.
// redis.xgroup_create("key", "group", "$", true);
id = redis.xadd( " key " , " * " , attrs.begin(), attrs.end());
// Read item by a consumer of a consumer group.
redis.xreadgroup( " group " , " consumer " , " key " , " > " , 1 , std::inserter(result, result.end()));
using PendingItem = std::tuple<std::string, std::string, long long , long long >;
std::vector<PendingItem> pending_items;
// Get pending items of a speicified consumer.
redis.xpending( " key " , " group " , " - " , " + " , 1 , " consumer " , std::back_inserter(pending_items));
redis.xack( " key " , " group " , id);
redis.xgroup_delconsumer( " key " , " group " , " consumer " );
redis.xgroup_destroy( " key " , " group " );If you have any problem on sending stream commands to Redis, please feel free to let me know.
Redis Modules enrich Redis. However, redis-plus-plus does not have built-in support/method for these modules, although you can use the generic interface to send commands related to these modules.
The generic command interface uses the second argument as the key for hashing. If your custom command places the key at a different argument (ie: module-name create key1 arg1 arg2 ), and you are using the RedisCluster client, then it will fail to send the command to the correct Redis instance. In this case you could use the following work-around:
auto redis_cluster = RedisCluster( " tcp://127.0.0.1:6379 " );
std::vector<std::string> raw_cmd;
raw_cmd.push_back( " module-name " );
raw_cmd.push_back( " create " );
raw_cmd.push_back( " key1 " );
raw_cmd.push_back( " arg1 " );
raw_cmd.push_back( " arg2 " );
// create it with a connection from the underlying connection pool
auto redis = redis_cluster.redis( " key1 " , false );
redis.command< void >(raw_cmd.begin(), raw_cmd.end());Fortunately, @wingunder did a great job to make the work easier. He wrote redis-plus-plus-modules, which is a header only project that has built-in support for some popular modules. If you need to work with Redis Modules, you should have a try.
@wingunder also contributes a lot to redis-plus-plus . Many thanks to @wingunder!
redis-plus-plus also supports async interface, however, async support for Transaction is still on the way.
The async interface depends on third-party event library, and so far, only libuv is supported.
You must install libuv (eg apt-get install libuv1-dev ) before install hiredis and redis-plus-plus . The required libuv version is 1.x .
hiredis v1.0.0's async interface is different from older version, and redis-plus-plus only supports hiredis v1.0.0 or later. So you need to ensure you've installed the right version of hiredis before installing redis-plus-plus . Also, you should NEVER install multiple versions of hiredis , otherwise, you'll get some wired problems. If you already installed an older version, remove it, and install a newer version.
When installing redis-plus-plus , you should specify the following command line option: -DREDIS_PLUS_PLUS_BUILD_ASYNC=libuv .
cmake -DCMAKE_PREFIX_PATH=/installation/path/to/libuv/and/hiredis -DREDIS_PLUS_PLUS_BUILD_ASYNC=libuv ..
make
make installThe async interface is similar to sync interface, except that you should include sw/redis++/async_redis++.h , and define an object of sw::redis::AsyncRedis , and the related methods return Future object (so far, only std::future and boost::future are supported, support for other implementations of future is on the way).
However, C++'s support for continuation and executor is not done yet, so the async interface also supports the old callback way. The following is the callback interface:
template <typename ReplyType>
void (sw::redis::Future<ReplyType> &&fut);
In the callback, in order to get the reply, you need to call sw::redis::Future<ReplyType>::get() . If something bad happened, get throws exception. So you need to catch possible exception in the callback. The callback runs in the underlying event loop thread, so DO NOT do slow operations in the callback, otherwise, it blocks the event loop and hurts performance.
笔记：
AsyncRedis alive before all callbacks have been executed (with some synchronization work). Because, once AsyncRedis is destroyed, it will stop the underlying event loop. And any commands that haven't sent to Redis yet, might fail. These notes also work with AsyncRedisCluster .
# include < sw/redis++/async_redis++.h >
ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ;
auto async_redis = AsyncRedis(opts, pool_opts);
Future<string> ping_res = async_redis.ping();
// Async interface returning Future object.
Future< bool > set_res = async_redis.set( " key " , " val " );
// Async interface with callback.
async_redis.set( " key " , " val " ,
[](Future< bool > &&fut) {
try {
auto set_res = fut. get ();
} catch ( const Error &err) {
// handle error
}
});
Future<Optional<string>> get_res = async_redis.get( " key " );
async_redis.get( " key " , [](Future<OptionalString> &&fut) {
try {
auto val = fut. get ();
if (val)
cout << *val << endl;
else
cout << " not exist " << endl;
} catch ( const Error &err) {
// handle error
}
});
unordered_map<string, string> m = {{ " a " , " b " }, { " c " , " d " }};
Future< void > hmset_res = async_redis.hmset( " hash " , m.begin(), m.end());
auto hgetall_res = async_redis.hgetall<std::unordered_map<std::string, std::string>>( " hash " );
cout << ping_res.get() << endl;
cout << set_res.get() << endl;
auto val = get_res.get();
if (val)
cout << *val << endl;
else
cout << " not exist " << endl;
hmset_res.get();
for ( const auto &ele : hgetall_res.get())
cout << ele.first << " t " << ele.second << endl;
// Generic interface.
// There's no *AsyncRedis::client_getname* interface.
// But you can use *Redis::command* to get the client name.
auto getname_res = async_redis.command<OptionalString>( " client " , " getname " );
val = getname_res.get();
if (val) {
std::cout << *val << std::endl;
}
async_redis.command<OptionalString>( " client " , " getname " ,
[](Future<OptionalString> &&fut) {
try {
auto val = fut. get ();
} catch ( const Error &e) {
// handle error
}
});
async_redis.command< long long >( " incr " , " number " ,
[](Future< long long > &&fut) {
try {
cout << fut. get () << endl;
} catch ( const Error &e) {
// handle error
}
});Aysnc interface also supports Redis Sentinel.
# include < sw/redis++/async_redis++.h >
SentinelOptions sentinel_opts;
sentinel_opts.nodes = {
{ " 127.0.0.1 " , 8000 },
{ " 127.0.0.1 " , 8001 },
{ " 127.0.0.1 " , 8002 }
};
sentinel_opts.connect_timeout = std::chrono::milliseconds( 100 );
sentinel_opts.socket_timeout = std::chrono::milliseconds( 100 );
auto sentinel = std::make_shared<AsyncSentinel>(sentinel_opts);
onnectionOptions connection_opts;
connection_opts.connect_timeout = std::chrono::milliseconds( 100 ); // Required.
connection_opts.socket_timeout = std::chrono::milliseconds( 100 ); // Required.
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ; // Optional. The default size is 1.
// Connect to master node.
AsyncRedis redis (sentinel, " mymaster " , Role::MASTER, connection_opts, pool_opts);
// The following code randomly connects to one of the slave nodes.
// AsyncRedis redis(sentinel, "mymaster", Role::SLAVE, connection_opts, pool_opts);
redis.set( " key " , " value " );
auto value = redis.get( " key " ).get(); The async support for sentinel is similar with the sync one, except that you need to create an AsyncSentinel object instead of a Sentinel object. Check Redis Sentinel for more details on SentinelOptions , ConnectionOptions and Role .
Aysnc interface also supports Redis Cluster. Instead of AsyncRedis , you need to create an AsyncRedisCluster object.
ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ;
auto async_cluster = AsyncRedisCluster(opts, pool_opts);
Future< bool > set_res = async_cluster.set( " key " , " val " );
Future<Optional<string>> get_res = async_cluster.get( " key " );
auto mget_res = async_cluster.mget<std::vector<OptionalString>>({ " {hashtag}key1 " , " {hashhag}key2 " , " {hashtag}key3 " });
unordered_map<string, string> m = {{ " a " , " b " }, { " c " , " d " }};
Future< void > hmset_res = async_redis.hmset( " hash " , m.begin(), m.end());
// Create an AsyncRedis object with hash-tag, so that we can send commands that has no key.
// It connects to Redis instance that holds the given key, i.e. hash-tag.
auto r = async_cluster.redis( " hash-tag " );
Future<string> ping_res = r.command<string>( " ping " ); NOTE : By default, when you use AsyncRedisCluster::redis(const StringView &hash_tag, bool new_connection = true) to create an AsyncRedis object, instead of picking a connection from the underlying connection pool, it creates a new connection to the corresponding Redis server. So this is NOT a cheap operation, and you should try to reuse this newly created AsyncRedis object as much as possible. If you pass false as the second parameter, you can create a AsyncRedis object without creating a new connection. However, in this case, you should be very careful, otherwise, you might get bad performance or even dead lock. Please carefully check the related pipeline section before using this feature. Also the returned AsyncRedis object is NOT thread-safe, and if it throws exception, you need to destroy it, and create a new one with the AsyncRedisCluster::redis method.
NOTE : I'm not quite satisfied with the interface of AsyncSubscriber . If you have a better idea, feel free to open an issue for discussion.
You can use AsyncSubscriber to subscribe to channels or patterns asynchronously. The interface is similar to Subscriber , except a few differences (please read Publish/Subscribe section first):
consume method for AsyncSubscriber . Once you setup callbacks, and subscribe to some channel, redis-plus-plus will run callbacks with received messages in the underlying event loop.AsyncSubscriber::subscribe , AsyncSubscriber::psubscriber and other related methods return Future<void> . You can use it to check if the subscription has been sent.AsyncSubscriber::on_error(ErrCallback &&) to handle possible errors. The error callback interface is: void (std::exception_ptr err) , and you can get the exception with given exception pointer. AsyncSubscriber is NOT thread-safe. If you want to call its member functions in multi-thread environment, you need to synchronize between threads manually.AsyncSubscriber is destroyed, the underlying connection will be closed. If there're still channels or patterns not unsubscribed, the error callback will be called. In order to avoid it, you need to call AsyncSubscriber::unsubscribe() or AsyncSubscriber::punsubscribe() to unsubscribe all channels or patterns before destroying AsyncSubscriber . NOTE: this behavior might be changed in the future, ie we'll unsubscribe channels and patterns in the destructor of AsyncSubscriber . The following example is a common pattern to use AsyncSubscriber :
// Create an `AsyncSubscriber`. You can create it with either an `AsyncRedis` or `AsyncRedisCluster` object.
auto sub = async_redis.subscriber();
// Set callbacks.
sub.on_message([](std::string channel, std::string msg) {
// Process message of MESSAGE type.
});
sub.on_pmessage([](std::string pattern, std::string channel, std::string msg) {
// Process message of PMESSAGE type.
});
sub.on_meta([](Subscriber::MsgType type, OptionalString channel, long long num) {
// Process message of META type.
});
// You need to set error callback to handle error.
sub.on_error([](std::exception_ptr e) {
try {
std::rethrow_exception (e);
} catch ( const std:: exception &err) {
std::cerr << " err: " << err. what () << std::endl;
}
});
// Subscribe to channels and patterns.
Future< void > fut1 = sub.subscribe( " channel " );
Future< void > fut2 = sub.psubscribe( " pattern1* " );
// Once you call `subscribe` or `psubscribe`, callbacks will be run in the underlying
// event loop automatically. NOTE : The following is an experimental feature, and might be modified or abandaned in the future.
By default, AsyncRedis and AsyncRedisCluster create a default event loop, and runs the loop in a dedicated thread to handle read and write operations. However, you can also share the underlying event loop with multiple AsyncRedis and AsyncRedisCluster objects. In order to do that, you need to create a std::shared_ptr<EventLoop> , and pass it to the constructors of AsyncRedis and AsyncRedisCluster .
auto event_loop = std::make_shared<EventLoop>();
auto redis = AsyncRedis(connection_opts, pool_opts, loop);
auto cluster = AsyncRedisCluster(connection_opts, pool_opts, Role::MASTER, loop); NOTE : You must ensure event_loop lives longer than AsyncRedis and AsyncRedisCluster objects.
Unfortunately, std::future doesn't support continuation so far, which is inconvenient. However, some other libraries, eg boost and folly, have continuation support.
By default, redis-plus-plus returns std::future for async interface. However, you can also make it return boost::future by specifying -DREDIS_PLUS_PLUS_ASYNC_FUTURE=boost when running cmake ( folly and other libraries might be supported in the future). Of course, in this case, you need to install Boost first (the minimum version requirement for Boost is 1.55.0 ).
cmake -DREDIS_PLUS_PLUS_BUILD_ASYNC=libuv -DREDIS_PLUS_PLUS_ASYNC_FUTURE=boost ..NOTE : When building your application code, don't forget to link boost related libs, eg -lboost_thread, -lboost_system.
Then you can take advantage of boost::future 's continuation support:
# include < sw/redis++/async_redis++.h >
ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
auto redis = AsyncRedis(opts);
auto fut = redis.get( " key " ).then([](sw::redis::Future<sw::redis::Optional<std::string>> fut) {
auto val = fut. get ();
if (val) cout << *val << endl;
});
// Do other things
// Wait for the continuation finishes.
fut.get();You can also use a thread pool to run the continuation:
# define BOOST_THREAD_PROVIDES_EXECUTORS
// You might also need to `#define BOOST_THREAD_USES_MOVE` with some version of Boost.
// See [this issue](https://github.com/sewenew/redis-plus-plus/issues/272) for detail.
# include < sw/redis++/async_redis++.h >
# include < boost/thread/executors/basic_thread_pool.hpp >
boost::executors::basic_thread_pool pool ( 3 );
auto fut = redis.get( " key " ).then(pool,
[](sw::redis::Future<sw::redis::Optional<std::string>> fut) {
auto val = fut. get ();
if (val) cout << *val << endl;
});
// Do other things
fut.get();redis-plus-plus also supports coroutine interface, however, coroutine support for Subscriber and Transaction is still on the way.
NOTE : Coroutine support is still experimental, and the interface might be changed in the future.
The coroutine interface depends on async interface, which depends on third-party event library. So you need to install libuv first, and hiredis v1.0.0 or later. Check async interface for detail.
When installing redis-plus-plus , you should specify the following command line options: -DREDIS_PLUS_PLUS_BUILD_ASYNC=libuv , -DREDIS_PLUS_PLUS_BUILD_CORO=ON and -DREDIS_PLUS_PLUS_CXX_STANDARD=20 .
cmake -DCMAKE_PREFIX_PATH=/installation/path/to/libuv/and/hiredis -DREDIS_PLUS_PLUS_CXX_STANDARD=20 -DREDIS_PLUS_PLUS_BUILD_ASYNC=libuv -DREDIS_PLUS_PLUS_BUILD_CORO=ON ..
make
make installThe coroutine interface is similar to sync interface, except that you should include sw/redis++/co_redis++.h , and define an object of sw::redis::CoRedis or sw::redis::CoRedisCluster , and the related methods return sw::redis::CoRedis::Awaiter<Result> or sw::redis::CoRedisCluster::Awaiter<Result> object.
笔记：
# include < sw/redis++/co_redis++.h >
# include < cppcoro/task.hpp >
# include < cppcoro/sync_wait.hpp >
ConnectionOptions opts;
opts.host = " 127.0.0.1 " ;
opts.port = 6379 ;
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ;
// `CoRedisCluster` has similar inteface as `CoRedis`.
// auto co_redis_cluster = CoRedisCluster(opts, pool_opts);
auto co_redis = CoRedis(opts, pool_opts);
cppcoro::sync_wait ([&co_redis]() -> cppcoro::task<> {
try {
co_await co_redis. set ( " key " , " val " );
auto val = co_await co_redis. get ( " key " );
if (val)
cout << *val << endl;
else
cout << " not exist " << endl;
co_await co_redis. command < long long >( " incr " , " num " );
val = co_await co_redis. command <OptionalString>( " get " , " num " );
} catch ( const Error &e) {
cout << e. what () << endl;
}
}());Coroutine interface also supports Redis Sentinel.
# include < sw/redis++/co_redis++.h >
SentinelOptions sentinel_opts;
sentinel_opts.nodes = {
{ " 127.0.0.1 " , 8000 },
{ " 127.0.0.1 " , 8001 },
{ " 127.0.0.1 " , 8002 }
};
sentinel_opts.connect_timeout = std::chrono::milliseconds( 100 );
sentinel_opts.socket_timeout = std::chrono::milliseconds( 100 );
auto sentinel = std::make_shared<CoSentinel>(sentinel_opts);
onnectionOptions connection_opts;
connection_opts.connect_timeout = std::chrono::milliseconds( 100 ); // Required.
connection_opts.socket_timeout = std::chrono::milliseconds( 100 ); // Required.
ConnectionPoolOptions pool_opts;
pool_opts.size = 3 ; // Optional. The default size is 1.
// Connect to master node.
CoRedis co_redis (sentinel, " mymaster " , Role::MASTER, connection_opts, pool_opts);
// The following code randomly connects to one of the slave nodes.
// CoRedis co_redis(sentinel, "mymaster", Role::SLAVE, connection_opts, pool_opts);
cppcoro::sync_wait ([&co_redis]() -> cppcoro::task<> {
try {
auto val = co_await co_redis. get ( " key " );
if (val)
cout << *val << endl;
else
cout << " not exist " << endl;
} catch ( const Error &e) {
cout << e. what () << endl;
}
}()); The coroutine support for sentinel is similar with the sync one, except that you need to create an CoSentinel object instead of a Sentinel object. Check Redis Sentinel for more details on SentinelOptions , ConnectionOptions and Role .
We can create many interesting data structures and algorithms based on Redis, such as Redlock. We call these data structures and algorithms as Redis Patterns . redis-plus-plus will support some of these patterns.
NOTE : These patterns will be first implemented on the patterns branch. I'd like to hear your feedback on the API of these patterns, and when these APIs become stable, I'll merge the code into the master branch. So APIs on the patterns branch are NOT stable, and might be changed in the future.
Redlock is a distributed lock based on Redis. Thanks to @wingunder's suggestion, redis-plus-plus supports Redlock now. @wingunder and I made two different implementation of Redlock: one based on Lua script, and the other based on transaction. The Lua script version should be faster, and also it has many other parameters to control the behavior. However, if you are not allowed to, or don't want to run Lua scripts inside Redis, you could try using the transaction version.
Also there's a high level API, which works like std::mutex . With this high level API, you don't need to manually extend the lock, instead, the lock will be automatically extened by redis-plus-plus.
The basic idea of acquiring a Redlock is setting a key in Redis if the key does not exist. Since Redis operation is atomic, when mutiple clients acquire the same lock, ie setting the same key if it does not exist, only one client wins, and others will find the key has already been set. So only one client can acquire the lock, and others have to wait and try again.
When setting the key, we also need to set a TTL/expireation for the key. Otherwise, if the winning client crashes, the lock cannot be acquired by others forever. However, it also brings a new problem. Since the key has a TTL, once you acquire the lock, you must ensure all code in critical section must be finished before the key expires. Otherwise, other clients might acquire the lock successfully when you are still running critical section code (ie more than one clients acquire the lock successfully). So when you run critical section code, you have to check if the key is going to be expired and extend the lock (ie extending the TTL) before key expires, from time to time.
Also, in order to make the algorithm more robust, normally we need to set key on multiple independent stand-alone Redis (not Redis Cluster).
There're still more details on the mechanism of Redlock. Please read Redlock's doc for more info, before using it.
The high level API is quite simple. It works like a std::mutex , and can be used with std::lock_guard and std::unique_lock . Also it can automatically extend the lock before the key expires. So that user code doesn't need to extend the lock manually. In order to use Redlock, you can create a RedMutex object with the following parameters:
Redis instances: There're two versions of Redlock, ie single instance version and multiple instances version. The multiple instances version is more robust.RedMutex should be created with the same resource id.RedMutexOptions (optional): Some options to control the behavior of RedMutex . If not specified, default options will be used. Check below for more detail.LockWatcher (optional): A watcher which will automatically extend the lock before it expires. So that you don't need to manually check if the lock has been expired. If no watcher is specified (the default behavior), redis-plus-plus will create a one for this Redlock. Check below for more detail. class RedMutex {
public:
RedMutex(std::initializer_list<std::shared_ptr<Redis>> masters,
const std::string &resource,
std::function<void (std::exception_ptr)> auto_extend_err_callback = nullptr,
const RedMutexOptions &opts = {},
const std::shared_ptr<LockWatcher> &watcher = nullptr);
void lock();
bool try_lock();
void unlock();
};
As we mentioned the high level API can automatically extend the lock. However, we might fail to extend the lock, eg connection to Redis is broken. In that case, the auto_extend_err_callback will be called, so that the application can be notified that the lock might no longer be locked, and stop running code in critical section.
The following is the prototype of error callback.
void (std::exception_ptr err);
If error callback is not set (the default behavior), the error will be ignored. And you're on risk of running critical section code with multiple clients.
struct RedMutexOptions {
std::chrono::milliseconds ttl;
std::chrono::milliseconds retry_delay;
bool scripting = true;
};
ttl , otherwise, you might fail to lock or fail to extend the lock.RedMutex::lock repeat trying to lock until it acquires the lock. If it fails, it wait retry_delay before the next retrying. 100 milliseconds by default. LockWatcher watches RedMutex , and try to extend the lock from time to time. You can construct RedMutex with a std::shared_ptr<LockWatcher> , so that it will watch the corresponding Redlock. LockWatcher does the work in a background thread. So creating a LockWatcher object also creates a std::thread . If you want to avoid creating multiple threads, you can construct multiple RedMutex with the same std::shared_ptr<LockWatcher> .
If you don't specify LockWatcher , RedMutex will create one (the default behavior), and start a thread. Although it's expensive to create thread, it's still quite cheap compared to acquiring a distributed lock.
RedMutex is NOT reentrant. If you try to lock a mutex which has already been locked by the current thread, the behavior is undefined.# include < memory >
# include < sw/redis++/redis++.h >
# include < sw/redis++/patterns/redlock.h >
auto redis = std::make_shared<Redis>( " tcp://127.0.0.1 " );
auto redis1 = std::make_shared<Redis>( " tcp://127.0.0.1:7000 " );
auto redis2 = std::make_shared<Redis>( " tcp://127.0.0.1:7001 " );
auto redis3 = std::make_shared<Redis>( " tcp://127.0.0.1:7002 " );
try {
{
// Create a `RedMutex` with a single stand-alone Redis and default settings.
RedMutex mtx (redis, " resource " );
std::lock_guard<RedMutex> lock (mtx);
}
{
// Create a `RedMutex` with multiple stand-alone Redis and default settings.
RedMutex mtx ({redis1, redis2, redis3}, " resource " );
std::lock_guard<RedMutex> lock (mtx);
}
{
RedMutexOptions opts;
opts. ttl = std::chrono::seconds ( 5 );
auto watcher = std::make_shared<LockWatcher>();
// Create a `RedMutex` with auto_extend_err_callback and other options.
RedMutex mtx ({redis1, redis2, redis3}, " resource " ,
[](std::exception_ptr err) {
try {
std::rethrow_exception (err);
} catch ( const Error &e) {
// Notify application code that the lock might no longer be locked.
}
},
opts, watcher);
std::unique_lock<RedMutex> lock (mtx, std::defer_lock);
lock. lock ();
lock. unlock ();
lock. try_lock ();
}
} catch ( const Error &err) {
// handle error.
} // Lua script version:
{
RedLockMutex mtx({redis1, redis2, redis3}, "resource");
// Not locked.
RedLock<RedLockMutex> lock(mtx, std::defer_lock);
// Try to get the lock, and keep 30 seconds.
// It returns the validity time of the lock, i.e. the lock is only
// valid in *validity_time*, after that the lock might be acquired by others.
// If failed to acquire the lock, throw an exception of Error type.
auto validity_time = lock.try_lock(std::chrono::seconds(30));
// Extend the lock before the lock expired.
validity_time = lock.extend_lock(std::chrono::seconds(10));
// You can unlock explicitly.
lock.unlock();
} // If unlock() is not called, the lock will be unlocked automatically when it's destroied.
// Transaction version:
{
RedMutex mtx({redis1, redis2, redis3}, "resource");
RedLock<RedMutex> lock(mtx, std::defer_lock);
auto validity_time = lock.try_lock(std::chrono::seconds(30));
validity_time = lock.extend_lock(std::chrono::seconds(30));
// You can unlock explicitly.
lock.unlock();
}
hset related methods return long long instead of bool . redis-plus-plus is written by sewenew, who is also active on StackOverflow.
Many thanks to all contributors of redis-plus-plus , especially @wingunder.
