Redis 中文文档

redis-cpp - lightweight C++ client library for Redis


redis-cpp is a C++17 library for executing Redis commands with support for pipelines and the publish / subscribe pattern. Moreover, you can extend the library with your own stream implementation to communicate with Redis. You can also use it like a RESP serializer (pure core). You need only know a couple of functions to start working with Redis.

  1. ``` sh
  2. // Connect to server
  3. auto stream = rediscpp::make_stream("localhost", "6379");
  4. // Execute command
  5. std::cout << rediscpp::execute(*stream, "ping").as() << std::endl;
  6. ```

And you may dive deeper if you feel the need.

NOTEIf you need a C++11 version you could switch to c++11 branch and use that one.

Version


1.1.0

Features


easy way to access Redis
pipelines
publish / subscribe
pure core in C++ for the RESP
extensible transport
header-only library if it's necessary
minimal dependencies
various levels of usage

License


Distributed under the MIT License

Compiler and OS


This has compiled and tested within gcc 9.3 and clang 10.0 on Ubuntu 20.04.You might try other compiler or OS.

NOTEAll code is a cross-platform.

Dependencies


Boost (at least 1.71 only for using with built-in implementation of transport).

Build and install


Build library


  1. ``` shell
  2. git clone https://github.com/tdv/redis-cpp.git  
  3. cd redis-cpp
  4. mkdir build  
  5. cd build  
  6. cmake ..  
  7. make  
  8. make install  
  9. ```

You can use CMAKE_INSTALL_PREFIX to select the installation directoryMoreover, you can use cmake options to configure the library for header-only or pure core.Instead of cmake options, you can define REDISCPP_HEADER_ONLY and use the library as header-only without any cmake file.

NOTEredis-cpp has two build options

Pure core only
Header-only

Use cmake -D with REDISCPP_HEADER_ONLY or REDISCPP_PURE_CORE. You can enable both options at the same time.You can use your own transport with the 'pure core' option.

If you need to use the header-only library, you can copy the folder redis-cpp from include/redis-cppin your project and define the macro REDISCPP_HEADER_ONLY before including the redis-cpp headers following the example code below:

  1. ``` sh
  2. #define REDISCPP_HEADER_ONLY
  3. #include <redis-cpp/stream.h>
  4. #include <redis-cpp/execute.h>

  6. // Include something else
  7. ```

Build examples


  1. ``` shell
  2. cd examples/{example_project}
  3. mkdir build  
  4. cd build  
  5. cmake ..  
  6. make  
  7. ```

Examples


NOTELook at the redis-docker folder to get all you need to start testing redis-cpp. There are files to build and run a Redis server in Docker.

Ping


Source code DescriptionThe "Ping" example demonstrates how to execute a Redis command.

  1. ``` sh
  2. // STD
  3. #include <cstdlib>
  4. #include <iostream>

  6. #include <redis-cpp/stream.h>
  7. #include <redis-cpp/execute.h>

  9. int main()
  10. {
  11.     try
  12.     {
  13.         auto stream = rediscpp::make_stream("localhost", "6379");
  14.         auto response = rediscpp::execute(*stream, "ping");
  15.         std::cout << response.as<std::string>() << std::endl;
  16.     }
  17.     catch (std::exception const &e)
  18.     {
  19.         std::cerr << "Error: " << e.what() << std::endl;
  20.         return EXIT_FAILURE;
  21.     }
  22.     return EXIT_SUCCESS;
  23. }

  25. ```

Set and Get data


Source code DescriptionThe example demonstrates how to set and get a value.

  1. ``` sh
  2. // STD
  3. #include <cstdlib>
  4. #include <iostream>

  6. #include <redis-cpp/stream.h>
  7. #include <redis-cpp/execute.h>

  9. int main()
  10. {
  11.     try
  12.     {
  13.         auto stream = rediscpp::make_stream("localhost", "6379");

  15.         auto const key = "my_key";

  17.         auto response = rediscpp::execute(*stream, "set",
  18.                 key, "Some value for 'my_key'", "ex", "60");

  20.         std::cout << "Set key '" << key << "': " << response.as<std::string>() << std::endl;

  22.         response = rediscpp::execute(*stream, "get", key);
  23.         std::cout << "Get key '" << key << "': " << response.as<std::string>() << std::endl;
  24.     }
  25.     catch (std::exception const &e)
  26.     {
  27.         std::cerr << "Error: " << e.what() << std::endl;
  28.         return EXIT_FAILURE;
  29.     }
  30.     return EXIT_SUCCESS;
  31. }
  32. ```

Pipeline


Source code DescriptionIt's a more complicated example which demonstrates how to use a pipeline within Redis to achieve better performance.

  1. ``` sh
  2. // STD
  3. #include <cstdlib>
  4. #include <iostream>

  6. #include <redis-cpp/stream.h>
  7. #include <redis-cpp/execute.h>

  9. int main()
  10. {
  11.     try
  12.     {
  13.         auto stream = rediscpp::make_stream("localhost", "6379");

  15.         int const N = 10;
  16.         auto const key_pref = "my_key_";

  18.         // Executing command 'SET' N times without getting any response
  19.         for (int i = 0 ; i < N ; ++i)
  20.         {
  21.             auto const item = std::to_string(i);
  22.             rediscpp::execute_no_flush(*stream,
  23.                 "set", key_pref + item, item , "ex", "60");
  24.         }

  26.         // Flush all
  27.         std::flush(*stream);

  29.         // Getting response for each sent 'SET' request
  30.         for (int i = 0 ; i < N ; ++i)
  31.         {
  32.             rediscpp::value value{*stream};
  33.             std::cout << "Set " << key_pref << i << ": "
  34.                       << value.as<std::string_view>() << std::endl;
  35.         }

  37.         // Executing command 'GET' N times without getting any response
  38.         for (int i = 0 ; i < N ; ++i)
  39.         {
  40.             rediscpp::execute_no_flush(*stream, "get",
  41.                 key_pref + std::to_string(i));
  42.         }

  44.         // Flush all
  45.         std::flush(*stream);

  47.         // Getting response for each sent 'GET' request
  48.         for (int i = 0 ; i < N ; ++i)
  49.         {
  50.             rediscpp::value value{*stream};
  51.             std::cout << "Get " << key_pref << i << ": "
  52.                       << value.as<std::string_view>() << std::endl;
  53.         }
  54.     }
  55.     catch (std::exception const &e)
  56.     {
  57.         std::cerr << "Error: " << e.what() << std::endl;
  58.         return EXIT_FAILURE;
  59.     }
  60.     return EXIT_SUCCESS;
  61. }
  62. ```

Resp


Source code DescriptionThe "Resp" example demonstrates a basic RESP serialization within redis-cpp without communication with Redis server. It's meant to show you how to use RESP serialization with redis-cpp library.

  1. ``` sh
  2. // STD
  3. #include <cstdlib>
  4. #include <iostream>
  5. #include <sstream>

  7. #include <redis-cpp/execute.h>

  9. namespace resps = rediscpp::resp::serialization;
  10. namespace respds = rediscpp::resp::deserialization;

  12. auto make_sample_data()
  13. {
  14.     std::ostringstream stream;

  16.     put(stream, resps::array{
  17.             resps::simple_string{"This is a simple string."},
  18.             resps::error_message{"This is an error message."},
  19.             resps::bulk_string{"This is a bulk string."},
  20.             resps::integer{100500},
  21.             resps::array{
  22.                 resps::simple_string("This is a simple string in a nested array."),
  23.                 resps::bulk_string("This is a bulk string in a nested array.")
  24.             }
  25.         });

  27.     return stream.str();
  28. }

  30. void print_value(respds::array::item_type const &value, std::ostream &stream)
  31. {
  32.     std::visit(rediscpp::resp::detail::overloaded{
  33.             [&stream] (respds::simple_string const &val)
  34.             { stream << "Simple string: " << val.get() << std::endl; },
  35.             [&stream] (respds::error_message const &val)
  36.             { stream << "Error message: " << val.get() << std::endl; },
  37.             [&stream] (respds::bulk_string const &val)
  38.             { stream << "Bulk string: " << val.get() << std::endl; },
  39.             [&stream] (respds::integer const &val)
  40.             { stream << "Integer: " << val.get() << std::endl; },
  41.             [&stream] (respds::array const &val)
  42.             {
  43.                 stream << "----- Array -----" << std::endl;
  44.                 for (auto const &i : val.get())
  45.                     print_value(i, stream);
  46.                 stream << "-----------------" << std::endl;
  47.             },
  48.             [&stream] (auto const &)
  49.             { stream << "Unexpected value type." << std::endl; }
  50.         }, value);
  51. }

  53. void print_sample_data(std::istream &istream, std::ostream &ostream)
  54. {
  55.     rediscpp::value value{istream};
  56.     print_value(value.get(), ostream);
  57. }

  59. int main()
  60. {
  61.     try
  62.     {
  63.         auto const data = make_sample_data();
  64.         std::cout << "------------ Serialization ------------" << std::endl;
  65.         std::cout << data << std::endl;

  67.         std::cout << "------------ Deserialization ------------" << std::endl;
  68.         std::istringstream stream{data};
  69.         print_sample_data(stream, std::cout);
  70.         std::cout << std::endl;
  71.     }
  72.     catch (std::exception const &e)
  73.     {
  74.         std::cerr << "Error: " << e.what() << std::endl;
  75.         return EXIT_FAILURE;
  76.     }
  77.     return EXIT_SUCCESS;
  78. }
  79. ```

Publish / Subscribe


Source code DescriptionThis is a more complicated example within redis-cpp which demonstrates how to publish messages and create a subscription to a queue. In the example a publisher and subscriber located in one process simultaniously, each one has its own stream to communicate with Redis. Usually, in real projects the publisher and subscriber are not located in one process.

  1. ``` sh
  2. // STD
  3. #include <cstdlib>
  4. #include <iostream>
  5. #include <thread>

  7. // BOOST
  8. #include <boost/thread.hpp>

  10. #include <redis-cpp/stream.h>
  11. #include <redis-cpp/execute.h>

  13. int main()
  14. {
  15.     try
  16.     {
  17.         auto const N = 100;
  18.         auto const queue_name = "test_queue";

  20.         bool volatile stopped = false;

  22.         // A message printer. The message from a queue.
  23.         auto print_message = [] (auto const &value)
  24.         {
  25.             using namespace rediscpp::resp::deserialization;
  26.             std::visit(rediscpp::resp::detail::overloaded{
  27.                    [] (bulk_string const &val)
  28.                    { std::cout << val.get() << std::endl; },
  29.                    [] (auto const &)
  30.                    { std::cout << "Unexpected value type." << std::endl; }
  31.                }, value);
  32.         };

  34.         // The subscriber is run in its own thread.
  35.         // It's some artificial example, when publisher
  36.         // and subscriber are working in one process.
  37.         // It's only for demonstration library abilities.
  38.         boost::thread subscriber{
  39.             [&stopped, &queue_name, &print_message]
  40.             {
  41.                 // Its own stream for a subscriber
  42.                 auto stream = rediscpp::make_stream("localhost", "6379");
  43.                 auto response = rediscpp::execute(*stream, "subscribe", queue_name);
  44.                 // An almost endless loop for getting messages from the queues.
  45.                 while (!stopped)
  46.                 {
  47.                     // Reading / waiting for a message.
  48.                     rediscpp::value value{*stream};
  49.                     // Message extraction.
  50.                     std::visit(rediscpp::resp::detail::overloaded{
  51.                             // We're wondered only an array in response.
  52.                             // Otherwise, there is an error.
  53.                             [&print_message] (rediscpp::resp::deserialization::array const &arr)
  54.                             {
  55.                                 std::cout << "-------- Message --------" << std::endl;
  56.                                 for (auto const &i : arr.get())
  57.                                     print_message(i);
  58.                                 std::cout << "-------------------------" << std::endl;
  59.                             },
  60.                             // Oops. An error in a response.
  61.                             [] (rediscpp::resp::deserialization::error_message const &err)
  62.                             { std::cerr << "Error: " << err.get() << std::endl; },
  63.                             // An unexpected response.
  64.                             [] (auto const &)
  65.                             { std::cout << "Unexpected value type." << std::endl; }
  66.                         }, value.get());
  67.                 }
  68.             }
  69.         };

  71.         // An artificial delay. It's not necessary in real code.
  72.         std::this_thread::sleep_for(std::chrono::milliseconds{200});

  74.         // Its own stream for a publisher.
  75.         auto stream = rediscpp::make_stream("localhost", "6379");

  77.         // The publishing N messages.
  78.         for (int i = 0 ; i < N ; ++i)
  79.         {
  80.             auto response = rediscpp::execute(*stream,
  81.                     "publish", queue_name, std::to_string(i));
  82.             std::cout << "Delivered to " << response.as<std::int64_t>()
  83.                       << " subscribers." << std::endl;
  84.         }

  86.         // An artificial delay. It's not necessary in real code.
  87.         // It's due to the artificiality of the example,
  88.         // where everything is in one process.
  89.         std::this_thread::sleep_for(std::chrono::milliseconds{200});

  91.         stopped = true;
  92.         std::this_thread::sleep_for(std::chrono::milliseconds{200});
  93.         // Why not?... Please, avoid it in real code.
  94.         // It's justified only in examples.
  95.         subscriber.interrupt();
  96.     }
  97.     catch (std::exception const &e)
  98.     {
  99.         std::cerr << "Error: " << e.what() << std::endl;
  100.         return EXIT_FAILURE;
  101.     }
  102.     return EXIT_SUCCESS;
  103. }
  104. ```

Conclusion


Take a look at a code above one more time. I hope you can find something useful for your own projects with Redis. I'd thought about adding one more level to wrap all Redis commands and refused this idea. A lot of useless work with a small outcome, because, in many cases we need to run only a handful of commands. Maybe it'll be a good idea in the future. Now you can use redis-cpp like lightweight library to execute Redis commands and get results  with minimal effort.

Enjoy your own projects with Redis!