NamedMux

String-keyed multiplexer over a Seam — the unbounded-namespace sibling of MuxSeam.

Produces independent Seam views — one per channel name — that share a single upstream collection of delegate's Seam.incoming. This satisfies the kuilt contract that Seam.incoming is single-collection: only NamedMux ever collects from delegate; each channel view subscribes to the internally-shared flow.

Where MuxSeam tags frames with a single byte (a hard ceiling of 256 channels, suited to a fixed handful of internal channels), NamedMux tags frames with a UTF-8 name, giving an effectively unbounded application namespace. The two compose by nesting: a MuxSeam tag can carry a whole NamedMux subtree, so only that subtree pays the wider header.

Framing

Every outbound frame is prefixed with [len:1 byte][name UTF-8], where len is the number of UTF-8 bytes in the name (1..255). Every inbound frame is filtered by its decoded name and delivered to the matching channel view with the header stripped. Frames whose name matches no channel view are silently discarded.

Late-subscriber semantics

Each view subscribes before channel returns and buffers frames in its reliable spool, so the caller can send immediately and collect the reply later. The shared upstream uses replay = 0: frames emitted before the matching channel is created are still discarded.

Channel identity

channel is idempotent: calling it twice with the same name returns the same Seam instance. Thread-safe: concurrent channel calls are serialised by an internal reentrant lock so the backing map is never raced.

Unread channels

Each view's spool holds DeliveryPolicy.DEFAULT_CAPACITY frames with Overflow.SUSPEND. An unread or slow view retains its frames and then blocks its internal subscriber. Once the shared buffer also fills, this backpressures the single upstream collector and can stall every channel on this mux. Consume created views promptly. The queue is bounded in frames per view, not bytes or total views; channel creation has no aggregate memory bound. This limitation also existed before subscriptions began starting at view creation.

Per-channel close

Closing a channel view ends that view only: its Seam.incoming completes, its Seam.state latches SeamState.Torn and its Seam.peers collapses to { selfId }, so a holder reading either learns the channel is gone. The base Seam remains live for all other channel views. The base closes only when the owner calls closeBase (or closes the delegate directly). This deliberate owner-driven design avoids fragile last-channel reference-counting and keeps lifecycle ownership clear: the entity that opened the delegate is the entity that closes it.

A send on a closed view is refused with an IllegalStateException, as Seam requires of any torn seam — it used to be swallowed, which was only defensible while the view still claimed to be SeamState.Woven (#2372).

Parameters

Samples

runTest(UnconfinedTestDispatcher()) {
    val loom = InMemoryLoom()
    val rawA = loom.host(Pattern("named-mux-demo"))
    val rawB = loom.join(InMemoryTag("b"))

    val muxA = NamedMux(rawA, backgroundScope)
    val muxB = NamedMux(rawB, backgroundScope)

    val chatA: Seam = muxA.channel("chat")
    val chatB: Seam = muxB.channel("chat")
    val cursorA: Seam = muxA.channel("cursors")

    // channel() is idempotent — same name returns the same Seam instance.
    check(muxA.channel("chat") === chatA)
    check(chatA !== cursorA)

    // Frames sent on "chat" arrive only on the matching channel view.
    val received = async { chatB.incoming.first() }
    chatA.broadcast("hello".encodeToByteArray())
    check(received.await().decodeToString() == "hello")
}