Redis Subscriber

The cpp_redis::redis_subscriber is meant to be used for PUB/SUB communication with the Redis server.

Please do not use cpp_redis::redis_client to subscribe to some Redis channels as:

• the behavior is undefined
• cpp_redis::redis_client is not meant for that

Methods

connect

void connect(const std::string& host = "127.0.0.1", unsigned int port = 6379, const disconnection_handler& handler = nullptr)

Description

Connects to the Redis Server. The connection is done synchronously. Throws redis_error in the case of a failure or if client if already connected.

Also, sets the disconnection handler which is called whenever a disconnection has occurred.

Disconnection handler is an std::function<void(redis_subscriber&)>.

Parameters

Type	Name	Description
const std::string&	host	Host to be connected to
unsigned int	port	Port of the hot to be connected to. If port is 0, host will be considered as a path to a unix socket and port will be ignored.
const disconnection_handler&	handler	Callback to be called on client disconnection

Return Value

None.

disconnect

void disconnect(bool wait_for_removal = false)

Description

Disconnects client from remote host. Throws redis_error if the client is not connected to any server.

Parameters

Type	Name	Description
bool	wait_for_removal	When sets to true, disconnect blocks until the underlying TCP client has been effectively removed from the io_service and that all the underlying callbacks have completed.

Return Value

None.

is_connected

bool is_connected(void)

Description

Returns whether the client is connected or not.

Parameters

None.

Return Value

Whether the client is connected or not.

subscribe

redis_subscriber& subscribe(const std::string& channel, const subscribe_callback_t& callback, const acknowledgement_callback_t& acknowledgement_callback = nullptr)

Description

Subscribes to the given channel and

• calls acknowledgement_callback once the server has acknowledged about the subscription.
• calls subscribe_callback each time a message is published on this channel.

subscribe_callback_t is an std::function<void(const std::string& channel, const std::string& message)>.

acknowledgement_callback_t is an std::function<void(int64_t nb_channel_subscribed)>.

The command is not effectively sent immediately but stored in an internal buffer until commit() is called.

Parameters

Type	Name	Description
const std::string&	channel	Channel to subscribe to
const subscribe_callback_t&	callback	Callback called whenever a message has been published on the channel
const acknowledgement_callback_t&	acknowledgement_callback	Callback called when the server has acknowledged the channel subscription

Return Value

Reference to the current instance of the redis_subscriber object.

psubscribe

redis_subscriber& psubscribe(const std::string& pattern, const subscribe_callback_t& callback, const acknowledgement_callback_t& acknowledgement_callback = nullptr)

Description

PSubscribes to the given pattern and:

• calls acknowledgement_callback once the server has acknowledged about the subscription.
• calls subscribe_callback each time a message is published in a channel matching the pattern.

subscribe_callback_t is an std::function<void(const std::string& channel, const std::string& message)>.

acknowledgement_callback_t is an std::function<void(int64_t nb_channel_subscribed)>.

The command is not effectively sent immediately but stored in an internal buffer until commit() is called.

Parameters

Type	Name	Description
const std::string&	pattern	Pattern to psubscribe to
const subscribe_callback_t&	callback	Callback called whenever a message has been published on the channel
const acknowledgement_callback_t&	acknowledgement_callback	Callback called when the server has acknowledged the channel subscription

Return Value

Reference to the current instance of the redis_subscriber object.

unsubscribe

redis_subscriber& unsubscribe(const std::string& channel)

Description

Unsubscribes from the given channel.

The command is not effectively sent immediately but stored in an internal buffer until commit() is called.

Parameters

Type	Name	Description
const std::string&	channel	Channel to unsubscribe from

Return Value

Reference to the current instance of the redis_subscriber object.

punsubscribe

redis_subscriber& punsubscribe(const std::string& pattern)

Description

Unsubscribes from the given pattern.

The command is not effectively sent immediately, but stored inside an internal buffer until commit() is called.

Parameters

Type	Name	Description
const std::string&	pattern	Pattern to punsubscribe from

Return Value

Reference to the current instance of the redis_subscriber object.

commit

redis_subscriber& commit(void)

Description

Sends all the commands that have been stored by calling send() since the last commit() call to the Redis server.

That is, pipelining is supported in a very simple and efficient way: sub.subscribe(...).psubscribe(...).unsubscribe(...).commit() will send the 3 commands at once (instead of sending 3 network requests, one for each command, as it would have been done without pipelining).

Pipelined commands are always removed from the buffer, even in the case of an error (for example, calling commit while the client is not connected, something that throws an exception).

Parameters

None.

Return Value

Reference to the current instance of the redis_subscriber object.