Quick Start
You are viewing the master version of this library.
The master and develop pages are shown here to provide access to the newest in-development in-progress documentation. See the "Documentation" link on this page.
Other aspects of the page will reflect the previous official version, or not be available until the next release.
Contributors: This Release
Boost.Redis
Boost.Redis is a high-level Redis client library built on top of Boost.Asio that implements the Redis protocol RESP3.
Full documentation is here.
Requirements
The requirements for using Boost.Redis are:
- Boost 1.84 or higher. Boost.Redis is included in Boost installations since Boost 1.84.
- C++17 or higher. Supported compilers include gcc 11 and later, clang 11 and later, and Visual Studio 16 (2019) and later.
- Redis 6 or higher (must support RESP3).
- OpenSSL.
The documentation assumes basic-level knowledge about Redis and Boost.Asio.
Building the library
To use the library it is necessary to include the following:
#include <boost/redis/src.hpp>
in exactly one source file in your applications. Otherwise, the library is header-only.
Boost.Redis unconditionally requires OpenSSL. Targets using Boost.Redis need to link to the OpenSSL libraries.
Tutorial
The code below uses a short-lived connection to ping a Redis server:
#include <boost/redis/connection.hpp>
#include <boost/asio/co_spawn.hpp>
#include <boost/asio/consign.hpp>
#include <boost/asio/detached.hpp>
#include <iostream>
namespace net = boost::asio;
using boost::redis::request;
using boost::redis::response;
using boost::redis::config;
using boost::redis::connection;
auto co_main(config const& cfg) -> net::awaitable<void>
{
auto conn = std::make_shared<connection>(co_await net::this_coro::executor);
conn->async_run(cfg, {}, net::consign(net::detached, conn));
// A request containing only a ping command.
request req;
req.push("PING", "Hello world");
// Response object.
response<std::string> resp;
// Executes the request.
co_await conn->async_exec(req, resp);
conn->cancel();
std::cout << "PING: " << std::get<0>(resp).value() << std::endl;
}
The roles played by the async_run and async_exec functions are:
connection::async_exec: executes the commands contained in the request and stores the individual responses in the response object. Can be called from multiple places in your code concurrently.connection::async_run: keeps the connection healthy. It takes care of hostname resolution, session establishment, health-checks, reconnection and coordination of low-level read and write operations. It should be called only once per connection, regardless of the number of requests to execute.
Server pushes
Redis servers can also send a variety of pushes to the client. Some of them are:
The connection class supports server pushes by means of the
connection::async_receive function, which can be
called in the same connection that is being used to execute commands.
The coroutine below shows how to use it:
auto
receiver(std::shared_ptr<connection> conn) -> net::awaitable<void>
{
request req;
req.push("SUBSCRIBE", "channel");
generic_response resp;
conn->set_receive_response(resp);
// Loop while reconnection is enabled
while (conn->will_reconnect()) {
// Reconnect to channels.
co_await conn->async_exec(req, ignore);
// Loop reading Redis pushes.
for (;;) {
error_code ec;
co_await conn->async_receive(resp, net::redirect_error(net::use_awaitable, ec));
if (ec)
break; // Connection lost, break so we can reconnect to channels.
// Use the response resp in some way and then clear it.
...
consume_one(resp);
}
}
}
Further reading
Full documentation is here.
Latest Boost.Redis posts
<h1>Boost.Redis</h1> <p>Boost.Redis is a high-level <a href="https://redis.io/">Redis</a> client library built on top of <a href="https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html">Boost.Asio</a> that implements the Redis protocol <a href="https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md">RESP3</a>.</p> <p>Full documentation is <a href="https://www.boost.org/doc/libs/master/libs/redis/index.html">here</a>.</p> <h2>Requirements</h2> <p>The requirements for using Boost.Redis are:</p> <ul> <li>Boost 1.84 or higher. Boost.Redis is included in Boost installations since Boost 1.84.</li> <li>C++17 or higher. Supported compilers include gcc 11 and later, clang 11 and later, and Visual Studio 16 (2019) and later.</li> <li>Redis 6 or higher (must support RESP3).</li> <li>OpenSSL.</li> </ul> <p>The documentation assumes basic-level knowledge about <a href="https://redis.io/docs/">Redis</a> and <a href="https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html">Boost.Asio</a>.</p> <h2>Building the library</h2> <p>To use the library it is necessary to include the following:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">#include <boost/redis/src.hpp> </code></pre> <p>in exactly one source file in your applications. Otherwise, the library is header-only.</p> <p>Boost.Redis unconditionally requires OpenSSL. Targets using Boost.Redis need to link to the OpenSSL libraries.</p> <h2>Tutorial</h2> <p>The code below uses a short-lived connection to <a href="https://redis.io/commands/ping/">ping</a> a Redis server:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">#include <boost/redis/connection.hpp> #include <boost/asio/co_spawn.hpp> #include <boost/asio/consign.hpp> #include <boost/asio/detached.hpp> #include <iostream> namespace net = boost::asio; using boost::redis::request; using boost::redis::response; using boost::redis::config; using boost::redis::connection; auto co_main(config const& cfg) -> net::awaitable<void> { auto conn = std::make_shared<connection>(co_await net::this_coro::executor); conn->async_run(cfg, {}, net::consign(net::detached, conn)); // A request containing only a ping command. request req; req.push("PING", "Hello world"); // Response object. response<std::string> resp; // Executes the request. co_await conn->async_exec(req, resp); conn->cancel(); std::cout << "PING: " << std::get<0>(resp).value() << std::endl; } </code></pre> <p>The roles played by the <code>async_run</code> and <code>async_exec</code> functions are:</p> <ul> <li><code>connection::async_exec</code>: executes the commands contained in the request and stores the individual responses in the response object. Can be called from multiple places in your code concurrently.</li> <li><code>connection::async_run</code>: keeps the connection healthy. It takes care of hostname resolution, session establishment, health-checks, reconnection and coordination of low-level read and write operations. It should be called only once per connection, regardless of the number of requests to execute.</li> </ul> <h2>Server pushes</h2> <p>Redis servers can also send a variety of pushes to the client. Some of them are:</p> <ul> <li><a href="https://redis.io/docs/manual/pubsub/">Pubsub messages</a>.</li> <li><a href="https://redis.io/docs/manual/keyspace-notifications/">Keyspace notifications</a>.</li> <li><a href="https://redis.io/docs/manual/client-side-caching/">Client-side caching</a>.</li> </ul> <p>The connection class supports server pushes by means of the <code>connection::async_receive</code> function, which can be called in the same connection that is being used to execute commands. The coroutine below shows how to use it:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">auto receiver(std::shared_ptr<connection> conn) -> net::awaitable<void> { request req; req.push("SUBSCRIBE", "channel"); generic_response resp; conn->set_receive_response(resp); // Loop while reconnection is enabled while (conn->will_reconnect()) { // Reconnect to channels. co_await conn->async_exec(req, ignore); // Loop reading Redis pushes. for (;;) { error_code ec; co_await conn->async_receive(resp, net::redirect_error(net::use_awaitable, ec)); if (ec) break; // Connection lost, break so we can reconnect to channels. // Use the response resp in some way and then clear it. ... consume_one(resp); } } } </code></pre> <h2>Further reading</h2> <p>Full documentation is <a href="https://www.boost.org/doc/libs/master/libs/redis/index.html">here</a>.</p>
-
Code Commits Commits authored to any Boost repository. With 1 contribution, you will earn the bronze badge for Code Commits.
-
Documentation Doc contributions using standardised Boost tooling (Antora / BoostLook). With 1 contribution, you will earn the bronze badge for Documentation.
-
Library Authoring Authored an original Boost library accepted into the collection. With 1 contribution, you will earn the bronze badge for Library Authoring.
-
Library Maintenance Number of libraries actively maintained. With 1 contribution, you will earn the bronze badge for Library Maintenance.
-
Library Review Formal review submissions on Boost proposals. With 1 contribution, you will earn the bronze badge for Library Review.
-
Library Versioning Authored new versions / releases of Boost libraries. With 10 contributions, you will earn the bronze badge for Library Versioning.
-
Mailing List Participation Participation on the Boost developers mailing list. With 1 contribution, you will earn the bronze badge for Mailing List Participation.
-
News Posts Published Articles / news posts published on Boost.org. With 1 contribution, you will earn the bronze badge for News Posts Published.
<h1>Boost.Redis</h1> <p>Boost.Redis is a high-level <a href="https://redis.io/">Redis</a> client library built on top of <a href="https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html">Boost.Asio</a> that implements the Redis protocol <a href="https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md">RESP3</a>.</p> <p>Full documentation is <a href="https://www.boost.org/doc/libs/master/libs/redis/index.html">here</a>.</p> <h2>Requirements</h2> <p>The requirements for using Boost.Redis are:</p> <ul> <li>Boost 1.84 or higher. Boost.Redis is included in Boost installations since Boost 1.84.</li> <li>C++17 or higher. Supported compilers include gcc 11 and later, clang 11 and later, and Visual Studio 16 (2019) and later.</li> <li>Redis 6 or higher (must support RESP3).</li> <li>OpenSSL.</li> </ul> <p>The documentation assumes basic-level knowledge about <a href="https://redis.io/docs/">Redis</a> and <a href="https://www.boost.org/doc/libs/latest/doc/html/boost_asio.html">Boost.Asio</a>.</p> <h2>Building the library</h2> <p>To use the library it is necessary to include the following:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">#include <boost/redis/src.hpp> </code></pre> <p>in exactly one source file in your applications. Otherwise, the library is header-only.</p> <p>Boost.Redis unconditionally requires OpenSSL. Targets using Boost.Redis need to link to the OpenSSL libraries.</p> <h2>Tutorial</h2> <p>The code below uses a short-lived connection to <a href="https://redis.io/commands/ping/">ping</a> a Redis server:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">#include <boost/redis/connection.hpp> #include <boost/asio/co_spawn.hpp> #include <boost/asio/consign.hpp> #include <boost/asio/detached.hpp> #include <iostream> namespace net = boost::asio; using boost::redis::request; using boost::redis::response; using boost::redis::config; using boost::redis::connection; auto co_main(config const& cfg) -> net::awaitable<void> { auto conn = std::make_shared<connection>(co_await net::this_coro::executor); conn->async_run(cfg, {}, net::consign(net::detached, conn)); // A request containing only a ping command. request req; req.push("PING", "Hello world"); // Response object. response<std::string> resp; // Executes the request. co_await conn->async_exec(req, resp); conn->cancel(); std::cout << "PING: " << std::get<0>(resp).value() << std::endl; } </code></pre> <p>The roles played by the <code>async_run</code> and <code>async_exec</code> functions are:</p> <ul> <li><code>connection::async_exec</code>: executes the commands contained in the request and stores the individual responses in the response object. Can be called from multiple places in your code concurrently.</li> <li><code>connection::async_run</code>: keeps the connection healthy. It takes care of hostname resolution, session establishment, health-checks, reconnection and coordination of low-level read and write operations. It should be called only once per connection, regardless of the number of requests to execute.</li> </ul> <h2>Server pushes</h2> <p>Redis servers can also send a variety of pushes to the client. Some of them are:</p> <ul> <li><a href="https://redis.io/docs/manual/pubsub/">Pubsub messages</a>.</li> <li><a href="https://redis.io/docs/manual/keyspace-notifications/">Keyspace notifications</a>.</li> <li><a href="https://redis.io/docs/manual/client-side-caching/">Client-side caching</a>.</li> </ul> <p>The connection class supports server pushes by means of the <code>connection::async_receive</code> function, which can be called in the same connection that is being used to execute commands. The coroutine below shows how to use it:</p> <pre class="highlightjs highlight"><code class="language-cpp hljs">auto receiver(std::shared_ptr<connection> conn) -> net::awaitable<void> { request req; req.push("SUBSCRIBE", "channel"); generic_response resp; conn->set_receive_response(resp); // Loop while reconnection is enabled while (conn->will_reconnect()) { // Reconnect to channels. co_await conn->async_exec(req, ignore); // Loop reading Redis pushes. for (;;) { error_code ec; co_await conn->async_receive(resp, net::redirect_error(net::use_awaitable, ec)); if (ec) break; // Connection lost, break so we can reconnect to channels. // Use the response resp in some way and then clear it. ... consume_one(resp); } } } </code></pre> <h2>Further reading</h2> <p>Full documentation is <a href="https://www.boost.org/doc/libs/master/libs/redis/index.html">here</a>.</p>
-
Achievement-based Reflects the depth of your contributions. Accumulate achievements to unlock five tiers; Bronze, Silver, Gold, Platinum and Diamond.
-
Tenure-based Awarded in recognition of your time on the platform. The longer you've been part of the Boost community, the higher the tier you unlock.
-
Boost day celebration A celebration of the day you joined Boost. Awarded annually to mark another year as part of the community.
