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)
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 createdHub
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 createdHub2
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 createdHub3
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 createdHub4
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 createdHubN
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
: TheHub
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
: TheHub2
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
: TheHub3
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
: TheHub4
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
: TheHubN
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
: TheHub
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
: TheHub2
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
: TheHub3
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
: TheHub4
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
: TheHubN
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()
}