Phoenix PubSub

https://hexdocs.pm/phoenix_pubsub/2.1.3/
Admin
Phoenix PubSub is a realtime publisher/subscriber service that enables message broadcasting across...
Tokens:3,964
Snippets:7
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Start Phoenix.PubSub in Supervision Tree

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

This snippet shows how to start the Phoenix.PubSub service within your Elixir supervision tree. It requires no external dependencies beyond Phoenix.PubSub itself.

```elixir
{Phoenix.PubSub, name: :my_pubsub}
```

--------------------------------

### Subscribe and Broadcast Messages with Phoenix.PubSub

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

Demonstrates the basic usage of Phoenix.PubSub for subscribing to a topic and broadcasting messages. This example uses the default `iex` environment and assumes Phoenix.PubSub is already running.

```elixir
alias Phoenix.PubSub
PubSub.subscribe(:my_pubsub, "user:123")
Process.info(self(), :messages)
PubSub.broadcast(:my_pubsub, "user:123", {:user_update, %{id: 123, name: "Shane"}})
Process.info(self(), :messages)
```

--------------------------------

### Subscription and System Management

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

Functions for subscribing to topics and managing the pubsub system.

```APIDOC
## POST /pubsub/subscribe

### Description
Subscribes the calling process to a specified topic within the pubsub system.

### Method
POST

### Endpoint
/pubsub/subscribe

### Parameters
#### Request Body
- **pubsub** (string) - Required - The name of the pubsub system
- **topic** (string) - Required - The topic to subscribe to, for example: "users:123"
- **opts** (keyword list) - Optional - Additional subscription options.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## GET /pubsub/node_name

### Description
Retrieves the node name of the running PubSub server.

### Method
GET

### Endpoint
/pubsub/node_name

### Parameters
#### Query Parameters
- **pubsub** (string) - Required - The name of the pubsub system

### Response
#### Success Response (200)
- **node_name** (string) - The name of the node.

#### Response Example
```json
{
  "node_name": "node@example.com"
}
```
```

```APIDOC
## POST /pubsub/child_spec

### Description
Generates a child specification for starting a pubsub process within a supervision tree.

### Method
POST

### Endpoint
/pubsub/child_spec

### Parameters
#### Request Body
- **options** (keyword list) - Required - Options for the pubsub child spec. Must include `:name`.
  - **`:name`** (atom) - Required - The name for the pubsub.
  - **`:adapter`** (module) - Optional - The adapter to use (defaults to `Phoenix.PubSub.PG2`).
  - **`:pool_size`** (integer) - Optional - The number of pubsub partitions to launch.

### Response
#### Success Response (200)
- **child_spec** (map) - The supervisor child specification.

#### Response Example
```json
{
  "child_spec": {
    "id": "my_pubsub",
    "start": { ... },
    "restart": :permanent
  }
}
```
```

--------------------------------

### Phoenix.PubSub Functions

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

This section details the core functions for broadcasting and subscribing to messages.

```APIDOC
## Broadcast Functions

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

#### Description
Raising version of `broadcast/4`.

#### Method
`POST` (or `BROADCAST` conceptually)

#### Endpoint
`/pubsub/broadcast`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

#### Description
Broadcasts message on given topic across the whole cluster.

#### Method
`POST` (or `BROADCAST` conceptually)

#### Endpoint
`/pubsub/broadcast`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

#### Description
Raising version of `broadcast_from/5`.

#### Method
`POST` (or `BROADCAST_FROM` conceptually)

#### Endpoint
`/pubsub/broadcast_from`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `from` (pid() | atom()) - Required - The process or identifier to broadcast from.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

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

#### Method
`POST` (or `BROADCAST_FROM` conceptually)

#### Endpoint
`/pubsub/broadcast_from`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `from` (pid() | atom()) - Required - The process or identifier to broadcast from.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

#### Description
Raising version of `direct_broadcast/5`.

#### Method
`POST` (or `DIRECT_BROADCAST` conceptually)

#### Endpoint
`/pubsub/direct_broadcast`

#### Parameters

##### Arguments
* `node_name` (node_name()) - Required - The target node name.
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

#### Description
Broadcasts message on given topic to a given node.

#### Method
`POST` (or `DIRECT_BROADCAST` conceptually)

#### Endpoint
`/pubsub/direct_broadcast`

#### Parameters

##### Arguments
* `node_name` (node_name()) - Required - The target node name.
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

#### Description
Broadcasts message on given topic only for the current node.

#### Method
`POST` (or `LOCAL_BROADCAST` conceptually)

#### Endpoint
`/pubsub/local_broadcast`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

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

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

#### Method
`POST` (or `LOCAL_BROADCAST_FROM` conceptually)

#### Endpoint
`/pubsub/local_broadcast_from`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `from` (pid() | atom()) - Required - The process or identifier to broadcast from.
* `topic` (topic()) - Required - The topic to broadcast on.
* `message` (message()) - Required - The message to broadcast.
* `dispatcher` (dispatcher()) - Optional - The custom dispatcher module. Defaults to `__MODULE__`.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the broadcast was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

## Subscription Functions

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

#### Description
Subscribes the caller to the PubSub adapter's topic.

#### Method
`POST` (or `SUBSCRIBE` conceptually)

#### Endpoint
`/pubsub/subscribe`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to subscribe to.
* `opts` (keyword()) - Optional - Additional options for subscription.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the subscription was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

### `unsubscribe(pubsub, topic)`

#### Description
Unsubscribes the caller from the PubSub adapter's topic.

#### Method
`POST` (or `UNSUBSCRIBE` conceptually)

#### Endpoint
`/pubsub/unsubscribe`

#### Parameters

##### Arguments
* `pubsub` (t()) - Required - The PubSub server name.
* `topic` (topic()) - Required - The topic to unsubscribe from.

#### Response

##### Success Response (200)
* `:ok` (atom) - Indicates the unsubscription was successful.

##### Response Example
```json
{
  "status": "ok"
}
```

## Utility Functions

### `child_spec(options)`

#### Description
Returns a child specification for pubsub with the given `options`.

#### Method
`GET` (or `CHILD_SPEC` conceptually)

#### Endpoint
`/pubsub/child_spec`

#### Parameters

##### Query Parameters
* `options` (keyword()) - Optional - Options for the child specification.

#### Response

##### Success Response (200)
* A child specification map.

##### Response Example
```json
{
  "id": "Phoenix.PubSub",
  "start": {"module": "Phoenix.PubSub", "method": "start_link", "args": [{"name": ":my_pubsub"}]},
  "type": "supervisor"
}
```

### `node_name(pubsub)`

#### Description
Returns the node name of the PubSub server.

#### Method
`GET`

#### Endpoint
`/pubsub/node_name`

#### Parameters

##### Query Parameters
* `pubsub` (t()) - Required - The PubSub server name.

#### Response

##### Success Response (200)
* `node_name()` - The node name.

##### Response Example
```json
{
  "node_name": "nonode@nohost"
}
```
```

--------------------------------

### Phoenix.PubSub Types and Function Signatures

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

This section outlines the various types and function signatures available in Phoenix.PubSub. It serves as a reference for understanding the expected inputs and outputs of the module's functions.

```elixir
@type dispatcher() :: module()
@type message() :: term()
@type node_name() :: atom() | binary()
@type t() :: atom()
@type topic() :: binary()
@spec broadcast!(t(), topic(), message(), dispatcher()) :: :ok
```

--------------------------------

### Broadcast Functions

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

Functions for broadcasting messages across the cluster.

```APIDOC
## POST /pubsub/broadcast

### Description
Broadcasts a message on a given topic across the whole cluster.

### Method
POST

### Endpoint
/pubsub/broadcast

### Parameters
#### Request Body
- **pubsub** (string) - Required - The name of the pubsub system
- **topic** (string) - Required - The topic to broadcast to, ie: "users:123"
- **message** (any) - Required - The payload of the broadcast
- **dispatcher** (module) - Optional - A custom dispatcher module.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## POST /pubsub/broadcast_from

### Description
Broadcasts a message on a given topic from a specified process across the whole cluster.

### Method
POST

### Endpoint
/pubsub/broadcast_from

### Parameters
#### Request Body
- **pubsub** (string) - Required - The name of the pubsub system
- **from** (pid) - Required - The process identifier that will send the message
- **topic** (string) - Required - The topic to broadcast to, ie: "users:123"
- **message** (any) - Required - The payload of the broadcast
- **dispatcher** (module) - Optional - A custom dispatcher module.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## POST /pubsub/direct_broadcast

### Description
Broadcasts a message on a given topic to a specific node in the cluster.

### Method
POST

### Endpoint
/pubsub/direct_broadcast

### Parameters
#### Request Body
- **node_name** (string) - Required - The target node name
- **pubsub** (string) - Required - The name of the pubsub system
- **topic** (string) - Required - The topic to broadcast to, ie: "users:123"
- **message** (any) - Required - The payload of the broadcast
- **dispatcher** (module) - Optional - A custom dispatcher module.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## POST /pubsub/local_broadcast

### Description
Broadcasts a message on a given topic only for processes on the current node.

### Method
POST

### Endpoint
/pubsub/local_broadcast

### Parameters
#### Request Body
- **pubsub** (string) - Required - The name of the pubsub system
- **topic** (string) - Required - The topic to broadcast to, ie: "users:123"
- **message** (any) - Required - The payload of the broadcast
- **dispatcher** (module) - Optional - A custom dispatcher module.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

```APIDOC
## POST /pubsub/local_broadcast_from

### Description
Broadcasts a message on a given topic from a specified process, only for processes on the current node.

### Method
POST

### Endpoint
/pubsub/local_broadcast_from

### Parameters
#### Request Body
- **pubsub** (string) - Required - The name of the pubsub system
- **from** (pid) - Required - The process identifier that will send the message
- **topic** (string) - Required - The topic to broadcast to, ie: "users:123"
- **message** (any) - Required - The payload of the broadcast
- **dispatcher** (module) - Optional - A custom dispatcher module.

### Response
#### Success Response (200)
- **status** (string) - Indicates success, e.g., "ok"

#### Response Example
```json
{
  "status": "ok"
}
```
```

--------------------------------

### Unsubscribe from Phoenix.PubSub Topic

Source: https://hexdocs.pm/phoenix_pubsub/2.1.3/phoenix_pubsub

Unsubscribes the caller from the PubSub adapter's topic. This function is used to remove a subscription. Note that all duplicate subscriptions are dropped when using `unsubscribe/2`.

```Elixir
@spec unsubscribe(t(), topic()) :: :ok
```
Tokens:
Raw