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 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. The hot path mutates a field in place (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, and the closed-world rewrite keeps the publish synchronous. This is the shape pond/metrics’ MetricsCollector uses.

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 tick() with a time-or-volume trigger rather than publishing per-update:

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
}
fn tick() {                                  // time trigger (scheduled)
    if self.pending > 0 { self.flush(); }
}
fn flush() {
    "snapshot" <- 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 span/JSON APIs (StringView, BytesView, std::json::*_span) 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 freed/overwritten memory:

let name = std::json::find_string_field(msg, "name");  // view into recv buf
self.read_msg();                                       // ← overwrites the buffer
println(name);                                         // ✗ dangling 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(std::json::find_string_field(msg, "name"));
self.read_msg();
println(name);   // ✓ owns its own copy

Forgetting this is now panic-guarded (a stale-view access exits with a diagnostic rather than reading garbage), so you’ll see a clear “view used after its buffer was overwritten” message instead of a silent corruption — but the fix is always to clone 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
    }
}

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:

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;
    }
}

Each reader’s recv 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 (TLS today) goes on pinned instead — see Concurrency & placement.