isolate.broadcast

import isolate.broadcast

isolate lifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelled isolate.broadcast.* needs import isolate.broadcast.

One-to-many (fan-out) publish-subscribe message distribution for isolate isolates.

Overview

While a standard Channel provides one-to-one or many-to-one message delivery (where each sent message is consumed by exactly one receiver), a Broadcast hub provides one-to-many publish-subscribe semantics. Every value published via Broadcast.send() is cloned and delivered to all currently active subscriber channels.

Broadcast is built on top of Zuri’s thread-safe Channel primitives, inheriting the same deep-copy memory isolation guarantees: published values cross isolate barriers cleanly without shared mutable state.

Re-exported by the isolate module, so import isolate is sufficient to use isolate.Broadcast and isolate.broadcast().

Subscription & Message Delivery

• Dynamic Subscription: Calling broadcast.subscribe() registers a new subscriber and returns a dedicated Channel for that subscriber. - No Historical Replay: Subscribers only receive messages published after they subscribe. Past messages published prior to subscription are not replayed. - Independent Consumer Queues: Each subscriber possesses its own queue buffer. One slow consumer reading slowly from its channel does not prevent fast consumers from receiving their copies at full speed.

Backpressure & Drop-on-Full Semantics

• Unbounded Subscriber Channels (capacity: 0 or nil): Each subscriber channel grows dynamically. Published messages are always delivered to all subscribers without dropping. - Bounded Subscriber Channels (capacity: n > 0): When a subscriber’s individual channel buffer reaches capacity n, the broadcaster uses a non-blocking send (timeout: 0). If the buffer is full, the message is dropped specifically for that slow subscriber rather than blocking the publisher or stalling other subscribers. This prevents a single lagging isolate from causing system-wide backpressure or deadlocks.

Lifecycle & Graceful Teardown

• Unsubscribing: A subscriber can be removed by calling broadcast.unsubscribe(ch). The channel stops receiving new broadcasts, but any previously queued messages remain readable. - Closing: Calling broadcast.close() closes the broadcast hub and all active subscriber channels. Subscribed isolates will drain their remaining buffered messages, after which subsequent recv() calls return nil. Attempting to call send() or subscribe() on a closed broadcast raises a IsolateError. - Automatic Pruning: If a subscriber closes its channel independently, the broadcast hub automatically detects the closed channel during the next send() and prunes it from the subscriber registry.

Examples

1. Publish-Subscribe Event Fan-Out

import isolate

var hub = isolate.broadcast()

# Isolate 1: Logging service
var sub1 = hub.subscribe()
var logger = isolate.spawn(def(ch) {
  while true {
    var msg = ch.recv()
    if msg == nil break
    echo "[Logger] ${msg}"
  }
}, sub1)

# Isolate 2: Metrics service
var sub2 = hub.subscribe()
var metrics = isolate.spawn(def(ch) {
  var count = 0
  while true {
    var msg = ch.recv()
    if msg == nil break
    count++
  }
  return count
}, sub2)

# Broadcast events to all subscribers
hub.send("event: user_login")
hub.send("event: page_view")
hub.close()

logger.join()
echo "Total metrics events: ${metrics.join()}"

2. Dynamic Unsubscription

import isolate

var hub = isolate.broadcast()
var sub = hub.subscribe()

hub.send("first message")
echo sub.recv() # "first message"

hub.unsubscribe(sub)
hub.send("second message") # Not delivered to sub

echo sub.try_recv() # nil
hub.close()

Functions

broadcast()

isolate.broadcast(capacity: ?int) -> Broadcast

Creates a new one-to-many Broadcast distribution hub.

import isolate
var hub = isolate.broadcast()

Parameters

• capacity (?int) — Per-subscriber buffer capacity (nil or 0 means unbounded).

Returns Broadcast

Classes

Broadcast

class isolate.Broadcast

A one-to-many publish-subscribe message distribution hub.

Constructor

isolate.Broadcast(capacity: ?int)

Constructs a new Broadcast hub.

import isolate
var hub = isolate.broadcast()      # Unbounded subscriber buffers
var bounded_hub = isolate.broadcast(50) # Drop on full after 50 items

Parameters

• capacity (?int) — Buffer capacity for each subscriber channel created via subscribe(). nil or 0 (the default) creates unbounded channels. When bounded, slow subscribers whose buffers are full will drop missed broadcasts rather than blocking the publisher.

Broadcast.subscribe()

isolate.Broadcast.subscribe()

Registers a new subscriber to this broadcast hub and returns a dedicated Channel for receiving published messages.

Subscribers only receive messages sent after the moment of subscription.

var sub_ch = hub.subscribe()
isolate.spawn(isolate_func, sub_ch)

Returns — Channel: A channel delivering published broadcasts.

Raises IsolateError if the broadcast hub has already been closed.

Broadcast.unsubscribe()

isolate.Broadcast.unsubscribe(channel)

Unregisters a subscriber channel from this broadcast hub.

The channel immediately stops receiving new broadcasts. Any messages already buffered in the channel remain readable via recv().

If channel was not subscribed or was already removed, this call is a no-op.

hub.unsubscribe(sub_ch)

Parameters

• channel (Channel) — The subscriber channel returned by subscribe().

Broadcast.send()

isolate.Broadcast.send(value)

Delivers value to all currently registered subscribers.

If a subscriber’s channel has a bounded capacity and is currently full, the message is dropped for that specific subscriber without blocking the sender or delaying other subscribers.

Any subscriber channels discovered to be closed are automatically pruned.

hub.send("alert: system update")

Parameters

• value (any) — The value or object graph to broadcast.

Raises IsolateError if the broadcast hub has been closed.

Broadcast.close()

isolate.Broadcast.close()

Closes the broadcast hub and all active subscriber channels.

Subscribed channels can continue draining any remaining buffered messages. Once drained, subsequent calls to recv() on subscriber channels will return nil. Calling send() or subscribe() after closing raises IsolateError.

hub.close()

Broadcast.is_closed()

isolate.Broadcast.is_closed()

Checks whether the broadcast hub has been closed.

if !hub.is_closed() {
  hub.send("active")
}

Returns — bool: true if closed, false otherwise.

Broadcast.subscriber_count()

isolate.Broadcast.subscriber_count()

Returns the current number of active subscribers registered to this hub.

echo "Subscribers listening: ${hub.subscriber_count()}"

Returns — int: Count of registered subscriber channels.

2026, Richard Ore and Zuri contributors