Relay Reference ¶

Relay is an in-process pub/sub system for real-time communication between connections.

Basic Usage ¶

from stario import Relay

relay = Relay()

# 1. Publish (synchronous, fire-and-forget)
relay.publish("topic.name", {"some": "data"})

# 2. Subscribe (async iterator)
async for subject, data in relay.subscribe("topic.name"):
    print(f"Update on {subject}: {data}")

Wildcards ¶

Relay supports prefix-based wildcards using *.

Patterns ¶

The Multiplayer Stream ¶

Open a persistent connection and re-render on updates.

async def updates(c: Context, w: Writer):
    # Initial state
    w.patch(render_list())

    # Wait for notifications
    async for _ in w.alive(relay.subscribe("list_updated")):
        w.patch(render_list())

Typed Payloads ¶

You can use generics for better IDE support.

@dataclass
class Msg:
    text: str

relay = Relay[Msg]()

relay.publish("chat", Msg(text="Hi"))

Memory & Performance ¶

• Zero Copy: Relay passes Python objects directly to subscribers.
• Async Safety: Safe to use across thousands of concurrent tasks.
• Cleanup: Subscription queues are garbage collected when the iterator exits.