redis-plus-plus

The library parses Redis protocol replies into C++ types. The mapping depends on the specific command's expected reply:

To use Pub/Sub, use Redis::publish to send messages and Redis::subscriber() to create a Subscriber object for receiving them.

Key Concepts:

• Redis::publish picks a connection from the pool. Multiple publishes might use different connections.
• Subscriber maintains its own dedicated connection (not from the pool). It inherits the ConnectionOptions from the Redis object used to create it.
• Thread Safety: Subscriber is NOT thread-safe. You must synchronize access manually if used in multi-threaded environments.
• Exception Handling: If a Subscriber throws an exception (other than ReplyError or TimeoutError), it is no longer usable and must be recreated.

Callbacks: You can register callbacks to handle different message types:

• on_message: For MESSAGE type.
• on_pmessage: For PMESSAGE type.
• on_meta: For meta-messages (SUBSCRIBE, UNSUBSCRIBE, PSUBSCRIBE, PUNSUBSCRIBE).

When a Redis command can return a NULL REPLY (like GET for a non-existent key), the library returns an Optional<T>.

• In C++17, Optional<T> is an alias for std::optional<T>.
• In C++11/14, it is a custom implementation.

You can check if a value exists by evaluating the Optional object in a boolean context and access the value using the dereference operator *.

// Or just: auto val = redis.get("key");
Optional<std::string> val = redis.get("key");

// Optional<T> has a conversion to bool.
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.
    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.
    }
}

To implement optimistic locking (Check-and-Set) using the WATCH command, you must use a Redis object that shares the same connection as your Transaction object. This is achieved via tx.redis().

Because WATCH relies on the connection state, you cannot get results from commands inside a transaction until .exec() is called. Using the Redis object returned by tx.redis() allows you to send WATCH and GET commands and receive immediate results within the same connection.

If a WatchError is caught, it means the watched key was modified by another client, and you should retry the transaction loop.

auto redis = Redis("tcp://127.0.0.1");
auto tx = redis.transaction();
auto r = tx.redis(); // Shares connection with tx

while (true) {
    try {
        r.watch("key");
        auto val = r.get("key");
        auto num = val ? std::stoi(*val) : 0;
        ++num;

        auto replies = tx.set("key", std::to_string(num)).exec();
        assert(replies.size() == 1 && replies.get<bool>(0) == true);
        break;
    } catch (const WatchError &err) {
        continue; // Retry
    } catch (const Error &err) {
        throw; // Transaction is invalid
    }
}

The Redis and RedisCluster objects are exception-safe and can be reused even if a connection is broken (e.g., an IoError is thrown); the client will attempt to reconnect automatically on the next command.

Important Exception Rule: If a Pipeline, Transaction, or Subscriber throws an exception, you must destroy that object and create a new one. You cannot reuse them after an exception.

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
    std::cout << err.what() << std::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
}

The Pipeline class allows you to batch multiple Redis commands to reduce Round Trip Time (RTT).

• Creation: Use Redis::pipeline() to create a pipeline. By default, this creates a new connection (not from the pool), which can be expensive.
• Sending Commands: Methods on the Pipeline object (like set, incr, etc.) do not return the reply; they return the Pipeline object itself, allowing for method chaining.
• Execution: Commands are only sent to Redis when Pipeline::exec() is called. This method returns a QueuedReplies object containing all results.
• Discarding: Use Pipeline::discard() to cancel all queued commands without sending them.
• Thread Safety: Pipeline is NOT thread-safe. Manual synchronization is required if used across threads.
• Exceptions: If a method throws an exception other than ReplyError, the Pipeline enters an invalid state and must be destroyed and recreated.