event_hub/topic

The topic module provides a way to manage and notify subscribers about events based on hierarchical topics. It supports creating observers that can filter events using one or more levels of topics, allowing more fine-grained control over event handling.

Examples

Single-Level Topic-Based Observer

import gleam/io
import event_hub/topic

pub fn main() {
  use hub <- topic.new()
  let unsubscribe_a =
    topic.subscribe(hub, ["a"], fn(value) {
      io.println("A received: " <> value)
    })

  let unsubscribe_b =
    topic.subscribe(hub, ["b"], fn(value) {
      io.println("B received: " <> value)
    })

  topic.notify(hub, ["a"], "Message for A")
  topic.notify(hub, ["b"], "Message for B")

  unsubscribe_a()
  unsubscribe_b()
}

Types

Represents a hub for managing event subscriptions and notifications based on a single level of topics.

pub opaque type Hub(value_type)

Represents a hub for managing event subscriptions and notifications based on two levels of topics.

pub opaque type Hub2(value_type)

Represents a hub for managing event subscriptions and notifications based on three levels of topics.

pub opaque type Hub3(value_type)

Represents a hub for managing event subscriptions and notifications based on four levels of topics.

pub opaque type Hub4(value_type)

Represents a hub for managing event subscriptions and notifications based on hierarchical topics.

pub type HubN(value_type)

Functions

pub fn new(in context: fn(Hub(a)) -> b) -> b

Creates a new single-level topic-based event hub, executes the given context with the hub.

Parameters

  • context: A function that takes the created Hub and returns a result.

Returns

The result of executing the context function.

Example

import event_hub/topic

pub fn example() {
  topic.new(fn(hub) {
    // Use the hub
    Nil
  })
}
pub fn new2(in context: fn(Hub2(a)) -> b) -> b

Creates a new two-level topic-based event hub, executes the given context with the hub.

Parameters

  • context: A function that takes the created Hub2 and returns a result.

Returns

The result of executing the context function.

Example

import event_hub/topic

pub fn example() {
  topic.new2(fn(hub) {
    // Use the hub
    Nil
  })
}
pub fn new3(in context: fn(Hub3(a)) -> b) -> b

Creates a new three-level topic-based event hub, executes the given context with the hub.

Parameters

  • context: A function that takes the created Hub3 and returns a result.

Returns

The result of executing the context function.

Example

import event_hub/topic

pub fn example() {
  topic.new3(fn(hub) {
    // Use the hub
    Nil
  })
}
pub fn new4(in context: fn(Hub4(a)) -> b) -> b

Creates a new four-level topic-based event hub, executes the given context with the hub.

Parameters

  • context: A function that takes the created Hub4 and returns a result.

Returns

The result of executing the context function.

Example

import event_hub/topic

pub fn example() {
  topic.new4(fn(hub) {
    // Use the hub
    Nil
  })
}
pub fn new_n(in context: fn(HubN(a)) -> b) -> b

Creates a new topic-based event hub, executes the given context with the hub, and stops the hub afterward.

Parameters

  • context: A function that takes the created HubN and returns a result.

Returns

The result of executing the context function.

Example

import event_hub/topic

pub fn example() {
  topic.new(fn(hub) {
    // Use the hub
    Nil
  })
}
pub fn notify(
  on hub: Hub(a),
  with topics: List(String),
  and value: a,
) -> Nil

Notifies subscribers of the hub about an event with the given single-level topics and value.

Parameters

  • hub: The Hub to notify.
  • topics: The list of topics associated with the event.
  • value: The value to send to all subscribers.

Example

import event_hub/topic

pub fn example(hub: topic.Hub(String)) {
  topic.notify(hub, ["topic1"], "event")
}
pub fn notify2(
  hub: Hub2(a),
  topics1: List(String),
  topics2: List(String),
  value: a,
) -> Nil

Notifies subscribers of the hub about an event with two levels of topics and a value.

Parameters

  • hub: The Hub2 to notify.
  • topics1: The first level of topics associated with the event.
  • topics2: The second level of topics associated with the event.
  • value: The value to send to all subscribers.

Example

import event_hub/topic

pub fn example(hub: topic.Hub2(String)) {
  topic.notify2(hub, ["topic1"], ["subtopic1"], "event")
}
pub fn notify3(
  hub: Hub3(a),
  topics1: List(String),
  topics2: List(String),
  topics3: List(String),
  value: a,
) -> Nil

Notifies subscribers of the hub about an event with three levels of topics and a value.

Parameters

  • hub: The Hub3 to notify.
  • topics1: The first level of topics associated with the event.
  • topics2: The second level of topics associated with the event.
  • topics3: The third level of topics associated with the event.
  • value: The value to send to all subscribers.

Example

import event_hub/topic

pub fn example(hub: topic.Hub3(String)) {
  topic.notify3(hub, ["topic1"], ["subtopic1"], ["subsubtopic1"], "event")
}
pub fn notify4(
  hub: Hub4(a),
  topics1: List(String),
  topics2: List(String),
  topics3: List(String),
  topics4: List(String),
  value: a,
) -> Nil

Notifies subscribers of the hub about an event with four levels of topics and a value.

Parameters

  • hub: The Hub4 to notify.
  • topics1: The first level of topics associated with the event.
  • topics2: The second level of topics associated with the event.
  • topics3: The third level of topics associated with the event.
  • topics4: The fourth level of topics associated with the event.
  • value: The value to send to all subscribers.

Example

import event_hub/topic

pub fn example(hub: topic.Hub4(String)) {
  topic.notify4(
    hub,
    ["topic1"],
    ["subtopic1"],
    ["subsubtopic1"],
    ["subsubsubtopic1"],
    "event",
  )
}
pub fn notify_n(
  on hub: HubN(a),
  with topics: List(List(String)),
  and value: a,
) -> Nil

Notifies subscribers of the hub about an event with the given topics and value. These notifications occur in parallel but notify_n waits for all of them to complete.

Parameters

  • hub: The HubN to notify.
  • topics: The list of topics associated with the event.
  • value: The value to send to all subscribers.

Example

import event_hub/topic

pub fn example(hub: topic.HubN(String)) {
  topic.notify_n(hub, [["topic1"]], "event")
}
pub fn subscribe(
  on hub: Hub(a),
  with topics: List(String),
  and callback: fn(a) -> Nil,
) -> fn() -> Nil

Subscribes to specific single-level topics and returns an unsubscribe function.

Parameters

  • hub: The Hub to add the callback to.
  • topics: The list of topics to subscribe to.
  • callback: The callback function to invoke when an event with matching topics occurs.

Returns

An Unsubscribe function that can be called to remove the callback.

Example

import gleam/io
import event_hub/topic

pub fn example(hub: topic.Hub(String)) {
  let unsubscribe =
    topic.subscribe(hub, ["topic1"], fn(value) {
      io.println("Received value: " <> value)
    })

  // To unsubscribe
  unsubscribe()
}
pub fn subscribe2(
  hub: Hub2(a),
  topics1: List(String),
  topics2: List(String),
  callback: fn(a) -> Nil,
) -> fn() -> Nil

Subscribes to specific two-level topics and returns an unsubscribe function.

Parameters

  • hub: The Hub2 to add the callback to.
  • topics1: The first level of topics to subscribe to.
  • topics2: The second level of topics to subscribe to.
  • callback: The callback function to invoke when an event with matching topics occurs.

Returns

An Unsubscribe function that can be called to remove the callback.

Example

import event_hub/topic
import gleam/io

pub fn example(hub: topic.Hub2(String)) {
  let unsubscribe =
    topic.subscribe2(hub, ["topic1"], ["subtopic1"], fn(value) {
      io.println("Received value: " <> value)
    })

  // To unsubscribe
  unsubscribe()
}
pub fn subscribe3(
  hub: Hub3(a),
  topics1: List(String),
  topics2: List(String),
  topics3: List(String),
  callback: fn(a) -> Nil,
) -> fn() -> Nil

Subscribes to specific three-level topics and returns an unsubscribe function.

Parameters

  • hub: The Hub3 to add the callback to.
  • topics1: The first level of topics to subscribe to.
  • topics2: The second level of topics to subscribe to.
  • topics3: The third level of topics to subscribe to.
  • callback: The callback function to invoke when an event with matching topics occurs.

Returns

An Unsubscribe function that can be called to remove the callback.

Example

import gleam/io
import event_hub/topic

pub fn example(hub: topic.Hub3(String)) {
  let unsubscribe =
    topic.subscribe3(
      hub,
      ["topic1"],
      ["subtopic1"],
      ["subsubtopic1"],
      fn(value) { io.println("Received value: " <> value) },
    )

  // To unsubscribe
  unsubscribe()
}
pub fn subscribe4(
  hub: Hub4(a),
  topics1: List(String),
  topics2: List(String),
  topics3: List(String),
  topics4: List(String),
  callback: fn(a) -> Nil,
) -> fn() -> Nil

Subscribes to specific four-level topics and returns an unsubscribe function.

Parameters

  • hub: The Hub4 to add the callback to.
  • topics1: The first level of topics to subscribe to.
  • topics2: The second level of topics to subscribe to.
  • topics3: The third level of topics to subscribe to.
  • topics4: The fourth level of topics to subscribe to.
  • callback: The callback function to invoke when an event with matching topics occurs.

Returns

An Unsubscribe function that can be called to remove the callback.

Example

import gleam/io
import event_hub/topic

pub fn example(hub: topic.Hub4(String)) {
  let unsubscribe =
    topic.subscribe4(
      hub,
      ["topic1"],
      ["subtopic1"],
      ["subsubtopic1"],
      ["subsubsubtopic1"],
      fn(value) { io.println("Received value: " <> value) },
    )

  // To unsubscribe
  unsubscribe()
}
pub fn subscribe_n(
  on hub: HubN(a),
  with topics: List(List(String)),
  and callback: fn(a) -> Nil,
) -> fn() -> Nil

Subscribes to specific topics and returns an unsubscribe function. The callback will be invoked only if the event topics match the subscription topics.

Parameters

  • hub: The HubN to add the callback to.
  • topics: The list of topics to subscribe to.
  • callback: The callback function to invoke when an event with matching topics occurs.

Returns

An Unsubscribe function that can be called to remove the callback.

Example

import gleam/io
import event_hub/topic

pub fn example(hub: topic.HubN(String)) {
  let unsubscribe =
    topic.subscribe_n(hub, [["topic1"]], fn(value) {
      io.println("Received value: " <> value)
    })

  // To unsubscribe
  unsubscribe()
}
Search Document