redis-plus-plus

中文交流群

Overview

Features

Branches

Installation

Install hiredis

Install redis-plus-plus

Run Tests (Optional)

Use redis-plus-plus In Your Project

Getting Started

API Reference

Connection

Send Command to Redis Server

Exception

Generic Command Interface

Publish/Subscribe

Pipeline

Transaction

Redis Cluster

Redis Sentinel

Redis Stream

Redis Modules

Async Interface

Coroutine Interface

Redis Patterns

Redlock

Author

This is a C++ client library for Redis. It's based on hiredis, and is compatible with C++ 17, C++ 14, and C++ 11.

NOTE: I'm not a native speaker. So if the documentation is unclear, please feel free to open an issue or pull request. I'll response ASAP.

Most commands for Redis.

Connection pool.

Redis scripting.

Thread safe unless otherwise stated.

Redis publish/subscribe.

Redis pipeline.

Redis transaction.

Redis Cluster.

Redis Sentinel.

STL-like interfaces.

Generic command interface.

Redis Stream.

Redlock.

Redis ACL.

TLS/SSL support.

Sync and Async interface.

Coroutine support.

The master branch is the stable branch, which passes all tests. The dev branch is unstable. If you want to contribute, please create pull request on dev branch.

Since redis-plus-plusis based on hiredis, you should install hiredisfirst. The minimum version requirement for hiredisis v0.12.1. However, the latest stable release of hiredisis always recommended.

NOTE: You must ensure that there's only 1 version of hiredis is installed. Otherwise, you might get some wired problems. Check the following issues for example: issue 135, issue 140 and issue 158.

Normally, you can install hirediswith a C++ package manager, and that's the easiest way to do it, e.g. sudo apt-get install libhiredis-dev. However, if you want to install the latest code of hiredis, or a specified version (e.g. async support needs hiredis v1.0.0 or later), you can install it from source.

Note again: DO NOT INSTALL MULTIPLE VERSIONS OF HIREDIS.

By default, hiredisis installed at /usr/local. If you want to install hiredisat non-default location, use the following commands to specify the installation path.

redis-plus-plusis built with CMAKE.

If hiredisis installed at non-default location, you should use CMAKE_PREFIX_PATH to specify the installation path of hiredis. By default, redis-plus-plusis installed at /usr/local. However, you can use CMAKE_INSTALL_PREFIX to install redis-plus-plusat non-default location.

Since version 1.3.0, by default, redis-plus-plusis built with the -std=c++17 standard. So that we can use the std::string_view and std::optional features. However, it can also be built with the -std=c++11 or -std=c++14 standard, and in that case, we have our own simple implementation of std::string_view and std::optional. In order to explicitly specify c++ standard, you can use the following cmake flag: -DREDIS_PLUS_PLUS_CXX_STANDARD=11.

NOTE: You should build redis-plus-plusand your application with the same standard, e.g. if you build redis-plus-pluswith C++17 standard, you MUST also build your application code with C++17 standard.

When compiling redis-plus-plus, it also compiles a test program, which might take a while. However, you can disable building test with the following cmake option: -DREDIS_PLUS_PLUS_BUILD_TEST=OFF.

By default, redis-plus-plusbuilds both a static library and a shared library. If you only want to build one of them, you can disable the other with -DREDIS_PLUS_PLUS_BUILD_STATIC=OFF or -DREDIS_PLUS_PLUS_BUILD_SHARED=OFF.

redis-plus-plusbuilds static library with -fPIC option, i.e. Position Independent Code, by default. However, you can disable it with -DREDIS_PLUS_PLUS_BUILD_STATIC_WITH_PIC=OFF.

Now hiredishas Windows support, and since Visual Studio 2017, Visual Studio has built-in support for CMake. So redis-plus-plusalso supports Windows platform now. It has been fully tested with Visual Studio 2017 and later on Win 10. I'm not familiar with Visual Studio environment, and the following doc might not be accurate. If you're familiar with the Windows platform, feel free to update this doc on how to install redis-plus-pluson Windows.

The following are some links on how to build CMake project with Visual Studio 2017 or later. If you're not familiar with it, you'd better read these instructions first:

CMake support in Visual Studio

CMake projects in Visual Studio

CMakeSettings.json schema reference

Open a project from a GitHub repo

NOTE: IMHO, Visual Studio 2017's support for CMake project is not very mature, and I recommend you to build hiredisand *redis-plus-plus with Visual Studio 2019.

First of all, you need to get the latest code of hiredison master branch. Older version might not support Windows platform. hiredis' CMakeLists.txt uses add_compile_definitions method, which is only supported by cmake 3.12 or later. However, Visual Studio 2017's cmake version is older than that. So if you're using Visual Studio 2017, you need to comment the following line in the CMakeLists.txt file:

You can use the Open Folderfeature to open hiredisproject, and build it with the instructions (links) mentioned above.

Since redis-plus-plusdepends on hiredis, we need to specify the installation paths of hiredisbefore building it. You can use the Open Folderfeature to open redis-plus-plusproject. You need to edit the CMakeSetting.jsonfile (automatically generated by Visual Studio) to set HIREDIS_HEADER, HIREDIS_LIBand TEST_HIREDIS_LIBvariables to specify the installation path of hiredis headers, installation path of hiredis dynamic library and installation path of hiredis static library. The following is an example of CMakeSetting.jsonfile:

Then you can build it the instructions (links) mentioned above. If you're building with Visual Studio 2017 in debug mode, you might get /bigobj error when building the test. In this case, you can disable building test by setting -DREDIS_PLUS_PLUS_BUILD_TEST=OFF or build it in Release mode.

NOTE:

Since 1.3.0, redis-puls-plusis built with C++17 by default, and you should also set your application code to be built with C++17. If you still want to build the redis-plus-pluswith C++11, you can set the REDIS_PLUS_PLUS_CXX_STANDARD cmake option to 11.

TLS/SSL support has not been tested on Windows yet.

On Windows platform, if your application code also needs to include windows.h. You must ensure that sw/redis++/redis++.his included before windows.h. Check this issue for detail.

Basic support for building a GNU/Debian package is supplied with the use of cmake. The following example shows how to build the Debian package:

The install prefix may be modified as follows:

redis-plus-plushas been fully tested with the following compilers:

If you build redis-plus-pluswith -DREDIS_PLUS_PLUS_BUILD_TEST=ON (the default behavior, and you can disable building test with -DREDIS_PLUS_PLUS_BUILD_TEST=OFF ), you'll get a test program in build/testdirectory: build/test/test_redis++.

In order to run the tests, you need to set up a Redis instance, and a Redis Cluster. Since the test program will send most of Redis commands to the server and cluster, you need to set up Redis of the latest version (by now, it's 5.0). Otherwise, the tests might fail. For example, if you set up Redis 4.0 for testing, the test program will fail when it tries to send the ZPOPMAX command (a Redis 5.0 command) to the server. If you want to run the tests with other Redis versions, you have to comment out commands that haven't been supported by your Redis, from test source files in redis-plus-plus/test/src/sw/redis++/directory. Sorry for the inconvenience, and I'll fix this problem to make the test program work with any version of Redis in the future.

NOTE: The latest version of Redis is only a requirement for running the tests. In fact, you can use redis-plus-pluswith Redis of any version, e.g. Redis 2.0, Redis 3.0, Redis 4.0, Redis 5.0.

NEVERrun the test program in production envronment, since the keys, which the test program reads or writes, might conflict with your application.

In order to run tests with both Redis and Redis Cluster, you can run the test program with the following command:

host* and portare the host and port number of the Redis instance.

cluster_node* and cluster_portare the host and port number of Redis Cluster. You only need to set the host and port number of a single node in the cluster, redis-plus-pluswill find other nodes automatically.

auth* is the password of the Redis instance and Redis Cluster. The Redis instance and Redis Cluster must be configured with the same password. If there's no password configured, don't set this option.

If you only want to run tests with Redis, you only need to specify host, portand authoptions:

Similarly, if you only want to run tests with Redis Cluster, just specify cluster_node, cluster_portand authoptions:

By default, the test program will not test running redis-plus-plusin multi-threads environment. If you want to do multi-threads test, which might cost a long time, you can specify the -moption:

If all tests have been passed, the test program will print the following message:

Otherwise, it prints the error message.

redis-plus-plusruns as fast as hiredis, since it's a wrapper of hiredis. You can run test_redis++in benchmark mode to check the performance in your environment.

-b* option turns the test program into benchmark mode.

thread_num* specifies the number of worker threads. 10 by default.

connection_pool_size* specifies the size of the connection pool. 5 by default.

request_num* specifies the total number of requests sent to server for each test. 100000 by default.

key_len* specifies the length of the key for each operation. 10 by default.

val_len* specifies the length of the value. 10 by default.

The bechmark will generate 100 random binary keys for testing, and the size of these keys is specified by key_len. When the benchmark runs, it will read/write with these keys. So NEVERrun the test program in your production environment, otherwise, it might inaccidently delete your data.

After compiling the code, you'll get both shared library and static library. Since redis-plus-plusdepends on hiredis, you need to link both libraries to your Application. Also don't forget to specify the c++ standard, -std=c++17, -std=c++14 or -std=c++11, as well as the thread-related option.

Take gcc as an example.

If hiredisand redis-plus-plusare installed at non-default location, you should use -I option to specify the header path.

If hiredisand redis-plus-plusare installed at non-default location, you should use -I and -L options to specify the header and library paths.