Phoenix.PubSub

Serves as a Notification and PubSub layer for broad use-cases. Used internally by Channels for pubsub broadcast.

PubSub Adapter Contract

PubSub adapters need to only implement start_link/2 and respond to a few process-based messages to integrate with Phoenix.

PubSub functions send the following messages:

• subscribe - sends: {:subscribe, pid, topic, link} respond with: :ok | {:error, reason} {:perform, {m, f a}}

• unsubscribe - sends: {:unsubscribe, pid, topic} respond with: :ok | {:error, reason} {:perform, {m, f a}}

• subscribers - respond with: :ok | {:error, reason} {:perform, {m, f a}}

• broadcast - sends {:broadcast, :none, topic, message} respond with: :ok | {:error, reason} {:perform, {m, f a}}

Additionally, adapters must implement start_link/2 with the following format:

def start_link(pubsub_server_name_to_locally_register, options)

Offloading work to clients via MFA response

The Phoenix.PubSub API allows any of its functions to handle a response from the adapter matching {:perform, {m, f a}}. The PubSub client will recursively invoke all MFA responses until a result is return. This is useful for offloading work to clients without blocking in your PubSub adapter. See Phoenix.PubSub.PG2 for an example usage.

Example

iex> PubSub.subscribe(MyApp.PubSub, self, "user:123")
:ok
iex> Process.info(self)[:messages]
[]
iex> PubSub.subscribers(MyApp.PubSub, "user:123")
[#PID<0.169.0>]
iex> PubSub.broadcast MyApp.PubSub, "user:123", {:user_update, %{id: 123, name: "Shane"}}
:ok
iex> Process.info(self)[:messages]
{:user_update, %{id: 123, name: "Shane"}}