actor patterns

state machines, fan-out, chatter, and more.

pattern 1 — state machine (rules= shines)

Classic traffic light. Different message types trigger different transitions:

actor = FX.StartActor(
    input=topic,
    initial_state=ET.Green(),
    rules={
        ('tick',      ET.Green):  constant_func([[FX.Print(content='🟢→🟡')], ET.Yellow()]),
        ('tick',      ET.Yellow): constant_func([[FX.Print(content='🟡→🔴')], ET.Red()]),
        ('tick',      ET.Red):    constant_func([[FX.Print(content='🔴→🟢')], ET.Green()]),
        ('emergency', Any):       constant_func([[FX.Print(content='🚨→🔴')], ET.Red()]),
    },
) | run

Rules are tuples of (msg_pattern, state_pattern). First match wins. Put narrow rules first, catch-alls last.

pattern-matching cheatsheet

pattern	matches when…
`Any`	anything
`Int`	value is an Int
`ET.Dog`	value is an `ET.Dog` entity
`greater_than(5)`	op returns True for value
`'tick'`	equality
`{1, 2, 3}`	value is in set

pattern 2 — accumulator (handler= shines)

Running stats, counters, log aggregation:

@zef_function
def running_sum(msg: Int, state: Int) -> Array:
    total = state + msg
    return [[FX.Print(content=f'total={total}')], total]

actor = FX.StartActor(input=topic, initial_state=0, handler=running_sum) | run

pattern 3 — fan-out (one topic, many actors)

Multiple actors subscribe to the same topic. Each processes every message independently.

topic = ET.Topic('🍃-c3c3c3c3c3c3c3c3c3c3')

a1 = FX.StartActor(input=topic, initial_state=0, handler=doubler) | run
a2 = FX.StartActor(input=topic, initial_state=0, handler=squarer) | run

FX.Publish(target=topic, content=5) | run
# doubler prints 10
# squarer prints 25

fan-out as a diagram

┌───▶ actor A (doubler) topic ────┼───▶ actor B (squarer) └───▶ actor C (logger) One publish, three independent executions.

pattern 4 — actor-to-actor chatter

An actor can publish to another topic as part of its effects list:

topic_a = ET.Topic('🍃-a1a1a1a1a1a1a1a1a1a1')
topic_b = ET.Topic('🍃-b2b2b2b2b2b2b2b2b2b2')

player_a = FX.StartActor(
    input=topic_a,
    initial_state=ET.Ready(),
    rules={
        (Any, Any): constant_func([
            [FX.Print(content='🏓 A'),
             FX.Publish(target=topic_b, content='ball')],
            ET.Ready(),
        ]),
    },
) | run

player_b = FX.StartActor(
    input=topic_b,
    initial_state=ET.Ready(),
    rules={
        (Any, Any): constant_func([
            [FX.Print(content='🏓 B'),
             FX.Publish(target=topic_a, content='ball')],
            ET.Ready(),
        ]),
    },
) | run

# serve
FX.Publish(target=topic_a, content='ball') | run
# 🏓 A
# 🏓 B
# 🏓 A
# 🏓 B
# ... bouncing at ~100k msg/s in Rust

pattern 5 — coordinator → subsystems

A coordinator receives high-level commands and fans out to subordinate topics:

coordinator = FX.StartActor(
    input=t_control,
    initial_state=ET.Normal(),
    rules={
        ('fire', ET.Normal): constant_func([
            [FX.Publish(target=t_alarm,     content='sound'),
             FX.Publish(target=t_sprinkler, content='activate'),
             FX.Publish(target=t_doors,     content='unlock')],
            ET.Emergency(),
        ]),
        ('all_clear', ET.Emergency): constant_func([
            [FX.Publish(target=t_alarm,     content='silence'),
             FX.Publish(target=t_sprinkler, content='deactivate'),
             FX.Publish(target=t_doors,     content='lock')],
            ET.Normal(),
        ]),
    },
) | run

Each subordinate (alarm, sprinkler, doors) is its own actor on its own topic. Coordinator just fires messages.

pattern 6 — per-connection actor (for websockets)

When someone connects to your WebSocket, spawn a fresh actor just for them:

FX.StartHTTPServer(
    routes={
        '/ws': ET.WebSocket(
            actor=FX.StartActor(
                initial_state=ET.Guest(),
                rules={
                    (ET.WSClientConnected, ET.Guest):       on_connect,
                    (String,                ET.Connected):   on_message,
                    (ET.WSClientDisconnected, Any):         on_disconnect,
                },
            ),
        ),
    },
    port=8000,
) | run

Each client = one actor. Private state per connection. The actor dies when the client disconnects.

fizzbuzz as an actor

@zef_function
def fizzbuzz(n: Int, state: Int) -> Array:
    if n % 15 == 0: out = 'FizzBuzz!'
    elif n % 3 == 0: out = 'Fizz'
    elif n % 5 == 0: out = 'Buzz'
    else: out = str(n)
    return [[FX.Print(content=out)], state + 1]

actor = FX.StartActor(input=topic, initial_state=0, handler=fizzbuzz) | run
for i in range(1, 16):
    FX.Publish(target=topic, content=i) | run

common shape tips

state shape is your choice

The state can be any zef value. Use the shape that fits your model:

Counter → an Int
State machine → an ET.Green() | ET.Yellow() | ET.Red() union
Fibonacci → [a, b] list
Chat history → a Dict with fields
Nothing to track → any constant value

introspect while running

# What's the current state of the traffic light?
FX.QueryActorState(actor=traffic_light) | run

# All logins, with just the username field extracted
FX.QueryActorState(transform=F.username) | run

# How many items does each actor have in its state?
FX.QueryActorState(transform=length) | run

build a door state-machine

States: ET.Locked(), ET.Unlocked(), ET.Open(). Messages: 'unlock', 'lock', 'open', 'close'. Rules:

Locked + unlock → Unlocked
Unlocked + lock → Locked
Unlocked + open → Open
Open + close → Unlocked

solution

actor = FX.StartActor(
    input=topic,
    initial_state=ET.Locked(),
    rules={
        ('unlock', ET.Locked):   constant_func([[FX.Print(content='🔓')], ET.Unlocked()]),
        ('lock',   ET.Unlocked): constant_func([[FX.Print(content='🔒')], ET.Locked()]),
        ('open',   ET.Unlocked): constant_func([[FX.Print(content='🚪')], ET.Open()]),
        ('close',  ET.Open):     constant_func([[FX.Print(content='▥')],  ET.Unlocked()]),
        (Any, Any):                    constant_func([[FX.Print(content='illegal')], Z]),   # keep state
    },
) | run

Next up: topics, SubscribeFX and timers. →