# `Raxol.PubSub`
[🔗](https://github.com/DROOdotFOO/raxol/blob/v2.8.0/lib/raxol/pubsub.ex#L1)

PubSub system for Raxol.

This module provides configuration and utilities for Phoenix.PubSub
integration in Raxol applications. It defines the PubSub server name
used throughout the application.

## Usage

In your application's supervision tree:

    children = [
      {Phoenix.PubSub, name: Raxol.PubSub}
    ]

Then subscribe and broadcast:

    Phoenix.PubSub.subscribe(Raxol.PubSub, "terminal:events")
    Phoenix.PubSub.broadcast(Raxol.PubSub, "terminal:events", {:key_press, key})

## Example

    # Subscribe to terminal events
    Raxol.PubSub.subscribe("terminal:events")

    # Broadcast an event
    Raxol.PubSub.broadcast("terminal:events", {:resize, 80, 24})

    # Broadcast from a specific node
    Raxol.PubSub.broadcast_from(self(), "terminal:events", {:input, "hello"})

# `broadcast`

```elixir
@spec broadcast(String.t(), term()) :: :ok
```

Broadcast a message to all subscribers of a topic.

## Example

    Raxol.PubSub.broadcast("terminal:events", {:key_press, :enter})

# `broadcast_from`

```elixir
@spec broadcast_from(pid(), String.t(), term()) :: :ok
```

Broadcast a message to all subscribers except the sender.

## Example

    Raxol.PubSub.broadcast_from(self(), "terminal:events", {:output, "Hello"})

# `child_spec`

```elixir
@spec child_spec(keyword()) :: Supervisor.child_spec()
```

Get the child spec for starting the PubSub server.

This can be used in your application's supervision tree.

## Example

    children = [
      Raxol.PubSub.child_spec([])
    ]

    Supervisor.start_link(children, strategy: :one_for_one)

# `local_broadcast`

```elixir
@spec local_broadcast(String.t(), term()) :: :ok
```

Broadcast a message locally (only to subscribers on this node).

## Example

    Raxol.PubSub.local_broadcast("terminal:events", {:local_event, data})

# `local_broadcast_from`

```elixir
@spec local_broadcast_from(pid(), String.t(), term()) :: :ok
```

Broadcast a message locally except to the sender.

## Example

    Raxol.PubSub.local_broadcast_from(self(), "terminal:events", {:output, "data"})

# `server_name`

```elixir
@spec server_name() :: Raxol.PubSub
```

The PubSub server name used throughout Raxol.

Returns the atom `Raxol.PubSub` which should be used when starting
the Phoenix.PubSub supervisor and when subscribing/broadcasting.

## Example

    {Phoenix.PubSub, name: Raxol.PubSub.server_name()}

# `subscribe`

```elixir
@spec subscribe(String.t()) :: :ok
```

Subscribe to a topic on the Raxol PubSub server.

This is a convenience wrapper around `Phoenix.PubSub.subscribe/2`.

## Example

    Raxol.PubSub.subscribe("terminal:events")

# `subscribe`

```elixir
@spec subscribe(String.t(), keyword()) :: :ok
```

Subscribe to a topic with options.

## Options

  - `:metadata` - Metadata to include with the subscription

## Example

    Raxol.PubSub.subscribe("terminal:events", metadata: %{user_id: 123})

# `unsubscribe`

```elixir
@spec unsubscribe(String.t()) :: :ok
```

Unsubscribe from a topic.

## Example

    Raxol.PubSub.unsubscribe("terminal:events")

---

*Consult [api-reference.md](api-reference.md) for complete listing*