phoenix_pubsub

v2.0.0

phoenix_pubsub v2.0.0 Phoenix.PubSub View Source

Realtime Publisher/Subscriber service.

Getting started

You start Phoenix.PubSub directly in your supervision tree:

{Phoenix.PubSub, name: :my_pubsub}

You can now use the functions in this module to subscribe and broadcast messages:

iex> alias Phoenix.PubSub
iex> PubSub.subscribe :my_pubsub, "user:123"
:ok
iex> Process.info(self(), :messages)
{:messages, []}
iex> PubSub.broadcast :my_pubsub, "user:123", {:user_update, %{id: 123, name: "Shane"}}
:ok
iex> Process.info(self(), :messages)
{:messages, [{:user_update, %{id: 123, name: "Shane"}}]}

Adapters

Phoenix PubSub was designed to be flexible and support multiple backends. There are two officially supported backends:

  • Phoenix.PubSub.PG2 - the default adapter that ships as part of Phoenix.PubSub. It uses Distributed Elixir, directly exchanging notifications between servers

  • Phoenix.PubSub.Redis - uses Redis to exchange data between servers. It requires the :phoenix_pubsub_redis dependency

See Phoenix.PubSub.Adapter to implement a custom adapter.

Custom dispatching

Phoenix.PubSub allows developers to perform custom dispatching by passing a dispatcher module which is responsible for local message deliveries.

The dispatcher must be available on all nodes running the PubSub system. The dispatch/3 function of the given module will be invoked with the subscriptions entries, the broadcaster identifier (either a pid or :none), and the message to broadcast.

You may want to use the dispatcher to perform special delivery for certain subscriptions. This can be done by passing the :metadata option during subscriptions. For instance, Phoenix Channels use a custom value to provide "fastlaning", allowing messages broadcast to thousands or even millions of users to be encoded once and written directly to sockets instead of being encoded per channel.

Link to this section Summary

Types

dispatcher()
message()
node_name()
t()
topic()

Functions

broadcast(pubsub, topic, message, dispatcher \\ __MODULE__)

Broadcasts message on given topic across the whole cluster.

broadcast!(pubsub, topic, message, dispatcher \\ __MODULE__)

Raising version of broadcast!/4.

broadcast_from(pubsub, from, topic, message, dispatcher \\ __MODULE__)

Broadcasts message on given topic from the given process across the whole cluster.

broadcast_from!(pubsub, from, topic, message, dispatcher \\ __MODULE__)

Raising version of broadcast_from!/5.

child_spec(options)

Returns a child specification for pubsub with the given options.

direct_broadcast(node_name, pubsub, topic, message, dispatcher \\ __MODULE__)

Broadcasts message on given topic to a given node.

direct_broadcast!(node_name, pubsub, topic, message, dispatcher \\ __MODULE__)

Raising version of direct_broadcast!/5.

local_broadcast(pubsub, topic, message, dispatcher \\ __MODULE__)

Broadcasts message on given topic only for the current node.

local_broadcast_from(pubsub, from, topic, message, dispatcher \\ __MODULE__)

Broadcasts message on given topic from a given process only for the current node.

node_name(pubsub)

Returns the node name of the PubSub server.

subscribe(pubsub, topic, opts \\ [])

Subscribes the caller to the PubSub adapter's topic.

unsubscribe(pubsub, topic)

Unsubscribes the caller from the PubSub adapter's topic.

Link to this section Types

Link to this type

dispatcher()

View Source 
dispatcher() :: module()
Link to this type

message()

View Source 
message() :: term()
Link to this type

node_name()

View Source 
node_name() :: atom() | binary()
Link to this type

t()

View Source 
t() :: atom()
Link to this type

topic()

View Source 
topic() :: binary()

Link to this section Functions

Link to this function

broadcast(pubsub, topic, message, dispatcher \\ __MODULE__)

View Source 
broadcast(t(), topic(), message(), dispatcher()) :: :ok | {:error, term()}

Broadcasts message on given topic across the whole cluster.

  • pubsub - The name of the pubsub system
  • topic - The topic to broadcast to, ie: "users:123"
  • message - The payload of the broadcast

A custom dispatcher may also be given as a fourth, optional argument. See the "Custom dispatching" section in the module documentation.

Link to this function

broadcast!(pubsub, topic, message, dispatcher \\ __MODULE__)

View Source 
broadcast!(t(), topic(), message(), dispatcher()) :: :ok

Raising version of broadcast!/4.

Link to this function

broadcast_from(pubsub, from, topic, message, dispatcher \\ __MODULE__)

View Source 
broadcast_from(t(), pid(), topic(), message(), dispatcher()) ::
  :ok | {:error, term()}

Broadcasts message on given topic from the given process across the whole cluster.

  • pubsub - The name of the pubsub system
  • topic - The topic to broadcast to, ie: "users:123"
  • message - The payload of the broadcast

A custom dispatcher may also be given as a fourth, optional argument. See the "Custom dispatching" section in the module documentation.

Link to this function

broadcast_from!(pubsub, from, topic, message, dispatcher \\ __MODULE__)

View Source 
broadcast_from!(t(), pid(), topic(), message(), dispatcher()) :: :ok

Raising version of broadcast_from!/5.

Link to this function

child_spec(options)

View Source 
child_spec(keyword()) :: Supervisor.child_spec()

Returns a child specification for pubsub with the given options.

The :name is required as part of options. The remaining options are described below.

Options

  • :name - the name of the pubsub to be started
  • :adapter - the adapter to use (defauls to Phoenix.PubSub.PG2)
  • :pool_size - number of pubsub partitions to launch (defaults to one partition for every 4 cores)
Link to this function

direct_broadcast(node_name, pubsub, topic, message, dispatcher \\ __MODULE__)

View Source

Broadcasts message on given topic to a given node.

  • node_name - The target node name
  • pubsub - The name of the pubsub system
  • topic - The topic to broadcast to, ie: "users:123"
  • message - The payload of the broadcast

DO NOT use this function if you wish to broadcast to the current node, as it is always serialized, use local_broadcast/4 instead.

A custom dispatcher may also be given as a fifth, optional argument. See the "Custom dispatching" section in the module documentation.

Link to this function

direct_broadcast!(node_name, pubsub, topic, message, dispatcher \\ __MODULE__)

View Source 
direct_broadcast!(node_name(), t(), topic(), message(), dispatcher()) :: :ok

Raising version of direct_broadcast!/5.

Link to this function

local_broadcast(pubsub, topic, message, dispatcher \\ __MODULE__)

View Source 
local_broadcast(t(), topic(), message(), dispatcher()) :: :ok

Broadcasts message on given topic only for the current node.

  • pubsub - The name of the pubsub system
  • topic - The topic to broadcast to, ie: "users:123"
  • message - The payload of the broadcast

A custom dispatcher may also be given as a fourth, optional argument. See the "Custom dispatching" section in the module documentation.

Link to this function

local_broadcast_from(pubsub, from, topic, message, dispatcher \\ __MODULE__)

View Source 
local_broadcast_from(t(), pid(), topic(), message(), dispatcher()) :: :ok

Broadcasts message on given topic from a given process only for the current node.

  • pubsub - The name of the pubsub system
  • topic - The topic to broadcast to, ie: "users:123"
  • message - The payload of the broadcast

A custom dispatcher may also be given as a fifth, optional argument. See the "Custom dispatching" section in the module documentation.

Link to this function

node_name(pubsub)

View Source 
node_name(t()) :: node_name()

Returns the node name of the PubSub server.

Link to this function

subscribe(pubsub, topic, opts \\ [])

View Source 
subscribe(t(), topic(), keyword()) :: :ok | {:error, term()}

Subscribes the caller to the PubSub adapter's topic.

  • server - The Pid registered name of the server
  • topic - The topic to subscribe to, for example: "users:123"
  • opts - The optional list of options. See below.

Duplicate Subscriptions

Callers should only subscribe to a given topic a single time. Duplicate subscriptions for a Pid/topic pair are allowed and will cause duplicate events to be sent; however, when using Phoenix.PubSub.unsubscribe/2, all duplicate subscriptions will be dropped.

Options

  • :metadata - provides metadata to be attached to this subscription. The metadata can be used by custom dispatching mechanisms. See the "Custom dispatching" section in the module documentation
Link to this function

unsubscribe(pubsub, topic)

View Source 
unsubscribe(t(), topic()) :: :ok

Unsubscribes the caller from the PubSub adapter's topic.