Redix v0.3.5 Redix.PubSub
Interface for the Redis PubSub functionality.
The rest of this documentation will assume the reader knows how PubSub works in Redis and knows the meaning of the following Redis commands:
SUBSCRIBE
andUNSUBSCRIBE
PSUBSCRIBE
andPUNSUBSCRIBE
PUBLISH
PubSub connections
Redix requires users to start a separate connection for using the PubSub
functionality: connections started via Redix.start_link/2
cannot be used for
PubSub, only for sending regular commands and pipelines of commands. In the
same fashion, "PubSub connections" (connections started via
Redix.PubSub.start_link/2
) cannot be used to send commands, only to
subscribe/unsubscribe to channels.
Reconnections
PubSub connections are subject to the same reconnection behaviour described in
the "reconnections" section of the documentation for the Redix
module. The
only difference is that a PubSub connection notifies subscribed clients when
it disconnects and reconnects. The exact form of the messages is described in
the "Messages" section.
Messages
All communication with a PubSub connection is done via (Elixir) messages: the recipients of these messages will be the processes specified at subscription time.
Every PubSub message sent by Redix has the same form, which is this:
{:redix_pubsub, message_type, message_subject, other_data}
Given this format, it's easy to match on all Redix PubSub messages by just
matching on {:redix_pubsub, _, _, _}
.
The message subject and the additional data strictly depend of the message type.
List of possible messages
The following is a list of all possible PubSub messages that Redix sends:
{:redix_pubsub, :subscribe, channel, nil}
- sent when a client successfully subscribes to achannel
usingsubscribe/4
.client_count
is the number of clients subscribed tochannel
. Note that whensubscribe/4
is called with more than one channel, a message like this one will be sent for each of the channels in the list.{:redix_pubsub, :psubscribe, pattern, nil}
- exactly like the previous message, except it's sent after calls topsubscribe/4
.{:redix_pubsub, :unsubscribe, channel, nil}
- sent when a client successfully unsubscribes from achannel
usingunsubscribe/4
.client_count
is the number of clients subscribed tochannel
. Note that whensubscribe/4
is called with more than one channel, a message like this one will be sent for each of the channels in the list.{:redix_pubsub, :punsubscribes, pattern, nil}
- exactly like the previous message, except it's sent after calls topunsubscribe/4
.{:redix_pubsub, :message, content, channel}
- sent when a message is published onchannel
.content
is the content of the message.{:redix_pubsub, :pmessage, content, {pattern, originating_channel}}
- sent when a message is published onoriginating_channel
and delivered to the recipient because that channels matches `pattern.{:redix_pubsub, :disconnected, subscribed_channels, nil}
- sent when a Redix PubSub connection disconnects from Redis.subscribed_channels
is the list of channels and patterns to which the recipient process was subscribed before the disconnection (elements of this list have the form{:channel, channel}
or{:pattern, pattern}
).{:redix_pubsub, :reconnected, nil, nil}
- sent when a Redix PubSub connection reconnects after a disconnection.
Example
This is an example of a workflow using the PubSub functionality.
{:ok, pubsub} = Redix.PubSub.start_link
{:ok, client} = Redix.start_link
:ok = Redix.PubSub.subscribe(pubsub, "foo", self())
# We wait for the subscription confirmation
{:redix_pubsub, :subscribe, "foo", _} = receive do m -> m end
Redix.command!(client, ~w(PUBLISH foo hello_foo)
{:redix_pubsub, :message, msg, channel} = receive do m -> m end
message #=> "hello_foo"
channel #=> "foo"
Redix.PubSub.unsubscribe(pubsub, "foo", self())
{:redix_pubsub, :unsubscribe, "foo", _} = receive do m -> m end
Summary
Functions
Subscribes recipient
to the given pattern or list of patterns
Subscribes recipient
to the given pattern or list of patterns, raising if
there's an error
Unsubscribes recipient
from the given pattern or list of patterns
Unsubscribes recipient
from the given pattern or list of patterns, raising
if there's an error
Starts a PubSub connection to Redis
Closes the connection to Redis conn
Subscribes recipient
to the given channel or list of channels
Subscribes recipient
to the given channel or list of channels, raising if
there's an error
Unsubscribes recipient
from the given channel or list of channels
Unsubscribes recipient
from the given channel or list of channels, raising
if there's an error
Types
pubsub_recipient ::
pid |
port |
atom |
{atom, node}
Functions
Specs
psubscribe(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) ::
:ok |
{:error, term}
Subscribes recipient
to the given pattern or list of patterns.
Works like subscribe/3
but subscribing recipient
to a pattern (or list of
patterns) instead of regular channels.
Upon successful subscription to each of the patterns
, a message will be sent
to recipient
with the following form:
{:redix_pubsub, :psubscribe, pattern, nil}
Examples
iex> Redix.psubscribe(conn, "ba*", self())
:ok
iex> flush()
{:redix_pubsub, :psubscribe, "ba*", nil}
:ok
Specs
psubscribe!(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) :: :ok
Subscribes recipient
to the given pattern or list of patterns, raising if
there's an error.
Works exactly like psubscribe/4
but raises if there's an error.
Specs
punsubscribe(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) ::
:ok |
{:error, term}
Unsubscribes recipient
from the given pattern or list of patterns.
This function basically "undoes" what psubscribe/3
does: it unsubscribes
recipient
from the given channel or list of channels.
Upon successful unsubscription from each of the patterns
, a message will be
sent to recipient
with the following form:
{:redix_pubsub, :punsubscribe, pattern, nil}
Examples
iex> Redix.punsubscribe(conn, "foo_*", self())
:ok
iex> flush()
{:redix_pubsub, :punsubscribe, "foo_*", nil}
:ok
Specs
punsubscribe!(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) :: :ok
Unsubscribes recipient
from the given pattern or list of patterns, raising
if there's an error.
Works exactly like punsubscribe/4
but raises if there's an error.
Specs
start_link(binary | Keyword.t, Keyword.t) :: GenServer.on_start
Starts a PubSub connection to Redis.
The behaviour of this function and the arguments it takes are exactly the same
as in Redix.start_link/2
; look at its documentation for more information.
Specs
stop(GenServer.server) :: :ok
Closes the connection to Redis conn
.
This function is asynchronous (fire and forget): it returns :ok
as soon as
it's called and performs the closing of the connection after that.
Examples
iex> Redix.PubSub.stop(conn)
:ok
Specs
subscribe(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) ::
:ok |
{:error, term}
Subscribes recipient
to the given channel or list of channels.
Subscribes recipient
(which can be anything that can be passed to send/2
)
to channels
, which can be a single channel as well as a list of channels.
For each of the channels in channels
which recipient
successfully
subscribes to, a message will be sent to recipient
with this form:
{:redix_pubsub, :subscribe, channel, nil}
Examples
iex> Redix.subscribe(conn, ["foo", "bar", "baz"], self())
:ok
iex> flush()
{:redix_pubsub, :subscribe, "foo", nil}
{:redix_pubsub, :subscribe, "bar", nil}
{:redix_pubsub, :subscribe, "baz", nil}
:ok
Specs
subscribe!(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) :: :ok
Subscribes recipient
to the given channel or list of channels, raising if
there's an error.
Works exactly like subscribe/4
but raises if there's an error.
Specs
unsubscribe(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) ::
:ok |
{:error, term}
Unsubscribes recipient
from the given channel or list of channels.
This function basically "undoes" what subscribe/3
does: it unsubscribes
recipient
from the given channel or list of channels.
Upon successful unsubscription from each of the channels
, a message will be
sent to recipient
with the following form:
{:redix_pubsub, :unsubscribe, channel, nil}
Examples
iex> Redix.unsubscribe(conn, ["foo", "bar", "baz"], self())
:ok
iex> flush()
{:redix_pubsub, :unsubscribe, "foo", nil}
{:redix_pubsub, :unsubscribe, "bar", nil}
{:redix_pubsub, :unsubscribe, "baz", nil}
:ok
Specs
unsubscribe!(GenServer.server, String.t | [String.t], pubsub_recipient, Keyword.t) :: :ok
Unsubscribes recipient
from the given channel or list of channels, raising
if there's an error.
Works exactly like unsubscribe/4
but raises if there's an error.