Composition patterns

The shape catalog names the seven building blocks — app locus, namespace locus, service locus, spawned child, @form collection with a domain facade, shape…

The shape catalog names the seven building blocks — app locus, namespace locus, service locus, spawned child, @form collection with a domain facade, shape type, free fn. This chapter is the next layer up: the compositions of those blocks that recur in real Hale services, distilled from production use. Reach for one of these when a problem feels like it needs a new language feature — usually it doesn’t, it needs one of these shapes.

The canonical answer to “I have N dynamic, keyed children with their own lifecycles” (and to the rejection of putting loci in a hashmap):

pinned reader  ──▶  cooperative manager  ──▶  keyed per-entity child
(owns the fd,        (accept()s a child       (subscribe ... where
 publishes events)    per new key)             key == self.id)

• A pinned locus owns the blocking input (socket, ring) on its own thread and publishes decoded events onto the bus.

• A cooperative manager subscribes to “new entity” events and accept()s one child per key. Declare release(c: Child) so each child is reclaimed when its flow ends (otherwise it’s a resident and lives until the manager dissolves — unbounded on a daemon; the compiler warns on that shape).

• The topic declares its routing field and each child subscribes with a key filter, so the bus delivers only that entity’s traffic:

  topic Update { payload: Tick; keyed_by id; }
  // in the child:
  bus { subscribe Update as on_update where key == self.id; }

  Keys can be scalars or String — a symbol id and a symbol name both work (String keys are hash-gated, so non-matching traffic costs one integer compare per entry).

This gives you per-entity state and lifecycle without a map of loci — the bus is the routing table, keyed. Filtering in the handler instead (if u.id == self.id) is the anti-pattern this composition deletes: it delivers every message to every child and discards N-1 of N.

A special case of the gateway with zero hardcoded topology: the manager doesn’t know its children up front. A subscription triggers the accept():

// manager
bus { subscribe "entity.first_seen" as on_seen of type Seen; }
fn on_seen(s: Seen) {
    // First message for this key → spawn its child now.
    // Bare instantiation inside a parent method attaches the child:
    // it triggers the enclosing accept(c) gatekeeper. `accept` is a
    // lifecycle hook the runtime invokes, never a method you call.
    Child { id: s.id };
}

The topology grows from the data. Combined with release, children appear on first contact and vanish when their flow ends — the process shape mirrors the live workload with no configuration. (If the manager doesn’t itself accept this child type, the child bubbles to the nearest accepting ancestor.)

You will want to write let n = self.metrics.incr("hits") on a hot path. Hale rejects locus methods that return locus values (the “CQRS” shape) — a method call that hands back a live locus reference breaks the closed-world ownership the substrate relies on. The rejection without a replacement strands you, so here is the migration:

• Pre-allocated handles at boot. Declare the counter/gauge loci as params of the owner, instantiated once at birth — std::metrics::counter(...) as a param default, as Concurrency & placement shows. The hot path mutates in place (self.ticks.inc(), or a plain self.hits = self.hits + 1) — no method returning a locus, no per-call allocation.
• Bus-routed single-writer store. For shared metrics, publish a MetricUpdate { name, delta } to a single collector locus that owns the store and applies updates in its handler. One writer, no contention.

Either way the hot path does an in-place field write or a publish — never a method that returns a locus.

When you produce data faster than you want to publish it (telemetry, book snapshots), gate the publish behind a time-or-volume trigger rather than publishing per-update:

type Update   { delta: Int; }
type Snapshot { total: Int; }
topic Updates   { payload: Update; }
topic Snapshots { payload: Snapshot; }

locus Batcher {
    params { pending: Int = 0; acc: Int = 0; }
    bus {
        subscribe Updates as on_update;
        publish   Snapshots;
    }

    fn on_update(u: Update) {
        self.pending = self.pending + 1;
        self.acc = self.acc + u.delta;           // accumulate in place
        if self.pending >= 100 { self.flush(); } // volume trigger
    }
    run() {                                      // time trigger
        while !self.draining {
            std::time::sleep(1s);
            if self.pending > 0 { self.flush(); }
        }
    }
    fn flush() {
        Snapshots <- Snapshot { total: self.acc };
        self.pending = 0;
    }
}

The accumulation is in-place; only the flush crosses the bus. This keeps the high-frequency path allocation-free and bounds publish volume independently of input volume.

The zero-copy APIs (StringView, BytesView, a builder’s .view() / .text_view(), the std::json::*_span cursors) hand you a view into a buffer you don’t own. That view is valid only until the next operation that overwrites the buffer — the next recv, the next ring read. Holding it across that boundary reads bytes that are no longer the ones you looked at:

let name = self.rx_buf.text_view();   // view into the receive buffer
self.read_msg();                      // ← refills rx_buf
println(name);                        // ✗ stale view

The rule: a view is valid until the next recv/overwrite; copy out to persist. Materialize it before the boundary:

let name = std::str::clone(self.rx_buf.text_view());
self.read_msg();
println(name);   // ✓ owns its own copy

Rendering a view copies it too: to_string(view), "name=" + view and f"{view}" each produce a String of their own, so any of them is as good a copy as std::str::clone.

A builder’s views are panic-guarded: reading one after its BytesBuilder changed exits with a diagnostic rather than reading garbage — violation: StringView read after source BytesBuilder mutated … — instead of a silent corruption. The fix is always to copy out before the overwriting call.

Every production connection locus converges on the same three fields: buffers held as params, reused every frame, never instantiated in a handler:

locus WsConn {
    params {
        rx_buf:  std::bytes::BytesBuilder = ...;  // frame reassembly
        tx_buf:  std::bytes::BytesBuilder = ...;  // send assembly
        scratch: std::bytes::BytesBuilder = ...;  // unmask / inflate
    }
    fn on_data(...) {
        std::io::tcp::recv_into(self.fd, self.rx_buf, 65536);
        // parse from self.rx_buf.view() — zero-copy
    }
}

The buffer argument is a std::bytes::BytesBuilder and nothing else — recv_into fills the builder’s tail in place, so a Bytes value or a plain Int is not a smaller version of the same thing. Pass one and hale check says so, at the argument:

`std::io::tcp::recv_into` argument 2: expected
`std::bytes::BytesBuilder`, got `Int`

A builder created inside the handler is a fresh heap buffer per message that reclaims only at method return (the compiler warns). Read with .view() / .text_view() and clear the buffer at the start of the next cycle, not the end of this one, so views handed out stay valid between frames. The full hot-path discipline lives in the styleguide §4 and Performance.

When one event reaches N consumers, render the shared payload once at ingest; each consumer adds only its per-consumer delta:

// ingest: render once
self.update_json = render_update(t);          // one render
Tick <- Update { json: self.update_json };    // fan out
// each connection: prepend its own seq only
fn on_update(u: Update) { self.send_frame("" + self.seq + u.json); }

N× a tiny prepend beats N× a full render. Pair it with the two-flavor emitter convention: a std::json::Builder version for cold paths (readable, allocating) and a raw-concat _pre version for the hot fan-out — keeping both documents which callers are hot.

One reader locus per source, parked on readiness — never a poll loop with set_recv_timeout:

locus Reader {
    params {
        port: Int = 0;
        src: std::io::udp::Reader =
            std::io::udp::Reader { addr: "127.0.0.1", port: self.port, cap: 2048 };
    }
    run() {
        while !self.draining {
            let frame = self.src.next() or raise;   // parks on EPOLLIN
            // decode `frame`, publish what it says
        }
    }
}

main locus App {
    params { r0: Reader = Reader { port: 9000 }; r1: Reader = Reader { port: 9001 }; }
    placement {
        r0: cooperative(pool = ingest) where async_io;
        r1: cooperative(pool = ingest) where async_io;
    }
}

fn main() { App { }; }

Each reader’s next() parks its coroutine on EPOLLIN; N readers share one pool worker with microsecond wakes (measured ~4 µs p50). Poll-scanner sleeps accumulate tail-latency debt that looks like a runtime problem but is the sleep schedule. Blocking I/O that can’t park (a TLS handshake, say) goes on pinned instead — see Concurrency & placement.