Module graph 

Runtime-checked graph, shape, port, and junction primitives.

This module contains Datum’s Akka-like graph layer: typed public ports, runtime-validated GraphDSL wiring, fused acyclic fast paths, and a queued fused interpreter for cyclic feedback topologies. Invalid wiring and illegal stage operations fail deterministically.

Structs

AnyInlet

Type-erased Inlet carrying the element TypeId and name.

AnyOutlet

Type-erased Outlet carrying the element TypeId and name.

AsyncBoundary

A pass-through marker that splits the graph into separate fused segments (one inlet, one outlet). Mirrors Akka’s .async boundary.

AsyncBoundaryExecutionConfig

Execution settings for the current graph async-boundary benchmark path.

AsyncCallback

A cloneable, thread-safe handle that injects a callback into the stage’s execution context. The callback is serialized with element processing: callbacks are buffered in a lock-protected queue and drained by the fused executor between element deliveries — the callback itself runs on the executor thread, not the invoker’s thread.

Balance

Fan out: route each element to one of outputs outlets, round-robin by demand (one inlet, N outlets).

BidiShape

Two inlets and two outlets arranged as two independent directions — the shape of a bidirectional flow (top: I1 → O1, bottom: I2 → O2). Explicit-only in the wiring DSL.

Broadcast

Fan out: push each element to all outputs outlets (one inlet, N outlets).

Buffer

A bounded in-stage buffer of capacity elements, applying strategy on overflow. In the synchronous fused executor it drains one element per step so it never overflows (a pass-through on the typed cyclic path); the erased executor runs the full buffering logic.

Concat

Fan in: fully drain each inlet in declared order before the next (N inlets, one outlet).

FanInShape

N inlets and one outlet — the shape of merge-style junctions (Merge, Concat, Interleave, OrElse, MergeSorted, …). Out defaults to In; MergeLatest uses Out = Vec<In>.

FanOutShape

One inlet and N outlets — the shape of fan-out junctions (Broadcast, Balance, Partition). Out defaults to In.

FanOutShape2

One inlet and two heterogeneously-typed outlets — the shape of Unzip and UnzipWith. Outlets are reached via .out0() / .out1().

FlowShape

One inlet and one outlet — a graph that behaves as a Flow. Re-exported as GraphFlowShape from the crate root.

FusedExecutionConfig

Execution bound for the fused executor. event_limit caps the number of push/pull events a single run may take, so an unproductive cycle surfaces StreamError::EventLimitExceeded instead of hanging. Defaults to 100M.

FusedExecutionReport

Result of a collecting run: the output vector plus instrumentation (events processed, async_boundary_crossings). Returned by the *_with_input_report methods.

FusedSegment

A maximal run of stages with no async boundary between them, executed together by the fused executor. Boundaries (AsyncBoundary stages) split a graph into consecutive segments.

FusedTerminalReport

Result of a terminal (count/fold) run: the reduced result plus the same instrumentation as FusedExecutionReport. Returned by the *_count_*_report / *_fold_*_report methods.

GraphBlueprint

An immutable, validated graph ready to run. Produced by GraphDsl::create/ try_create. Carries the external Shape, the stages, the wired edges, the precomputed fused segments, and graph-level Attributes. The run_* methods are defined in the executor module; running one never mutates the blueprint, so it can be reused and run concurrently.

GraphBuilder

Mutable scratch state for assembling a graph inside a GraphDsl closure.

GraphDsl

Entry points for building graphs. create takes a closure returning the shape directly, try_create a closure returning StreamResult<Shape> (so ? works on connect/try_wire), and partial builds a reusable PartialGraph fragment.

GraphStageLogic

Per-materialization runtime state and handlers for one stage.

Identity

Pass elements through unchanged (one inlet, one outlet). Akka’s identity.

Inlet

A typed graph inlet: the downstream end of an edge that accepts T elements.

InletCursor

Interleave

Fan in: round-robin across inputs inlets in chunks of segment_size (N inlets, one outlet). eager_close stops when any inlet completes.

MapStage

Apply f to each element, mapping In to Out (one inlet, one outlet).

Merge

Fan in: emit from whichever of inputs inlets has an element available (N inlets, one outlet). Order across inlets is not guaranteed.

MergeLatest

Fan in: once every inlet has emitted at least once, emit a Vec<T> snapshot of the latest element per inlet on each push (N inlets, one Vec<T> outlet). eager_complete ends the stream as soon as any inlet completes.

MergePreferred

Fan in: always drain the single preferred inlet ahead of the secondary_ports secondaries (1 preferred + N secondary inlets, one outlet).

MergePreferredShape

One preferred inlet, N secondary inlets, and one outlet — the shape of MergePreferred. Explicit-only in the wiring DSL (use .preferred() / .secondary(i)).

MergePrioritized

Fan in: emit on a deterministic weighted schedule — inlet i is drained weights[i] times per cycle (N inlets, one outlet). Unlike Akka’s MergePrioritized, the schedule is fixed, not randomized.

MergeSequence

Fan in: reassemble elements in gap-free ascending order of the sequence number extract_sequence returns (N inlets, one outlet). Fails on a missing or duplicate sequence number.

MergeSorted

Fan in: merge two already-sorted inlets into one sorted outlet (2 inlets, one outlet). Requires T: Ord.

OrElse

Fan in: emit the primary inlet; fall back to the secondary only if the primary completes without emitting (2 inlets, one outlet).

Outlet

A typed graph outlet: the upstream end of an edge that emits T elements.

OutletCursor

PartialGraph

A reusable graph fragment: a builder closure plus its Shape, importable into multiple parent graphs via GraphBuilder::import. Still a blueprint — the closure runs (allocating fresh ports) each time it is imported. Aliased as ImportedGraph.

Partition

Fan out: route each element to the outlet index partitioner returns (one inlet, N outlets). eager_cancel cancels the whole stage when any one outlet cancels; otherwise it runs while at least one outlet is live.

PortAllocator

Hands a GraphStage fresh, uniquely-identified ports when its shape is allocated. Each inlet/outlet call draws a new global PortId; the allocator itself is stateless.

PortId

A process-global unique identifier for a port, drawn from a single atomic counter. Stages allocate contiguous id blocks; ids are not graph-local and do not start at zero.

SinkShape

One inlet, no outlets — a graph that behaves as a Sink.

SourceShape

One outlet, no inlets — a graph that behaves as a Source.

StageSpec

The blueprint description of a stage: its name, erased ports, the internal kind the executor switches on, async-boundary flag, and attributes. Construct one with StageSpec::opaque for a custom stage that runs its own GraphStageLogic; built-in stages use the crate-internal constructors.

TakeWhile

Emit elements while predicate holds, then complete (one inlet, one outlet).

Unzip

Fan out: split each (A, B) pair, sending A to out0 and B to out1 (one inlet, two outlets). Built on UnzipWith with the identity split.

UnzipWith

Fan out: apply split to each element, sending the first component to out0 and the second to out1 (one inlet, two outlets).

WirePair

Zip

Fan in: pair one element from each inlet into (Left, Right); completes when either inlet completes (2 inlets, one outlet).

ZipShape

Two heterogeneously-typed inlets and one (Left, Right) outlet — the shape of Zip. Inlets are reached via .in0() / .in1().

Enums

PortKind

Whether a port is an inlet (accepts elements) or an outlet (emits them).

Traits

Graph

Anything exposing a graph Shape — implemented by GraphBlueprint.

GraphStage

A stage blueprint: declares its Shape, builds its StageSpec, and (for opaque stages) creates the runtime GraphStageLogic. Implement this to add a custom graph stage; the built-in junctions implement it too. add-ing a stage to a GraphBuilder allocates its ports and records the spec.

InHandler

Reacts to events on one inlet. The default on_upstream_failure fails the whole stage; override any method a stage needs.

OutHandler

Reacts to events on one outlet. The default on_downstream_finish completes the whole stage; override any method a stage needs.

PortRef

Common read accessors over a typed port, independent of element type or direction. Implemented by both Inlet and Outlet; used by handler helpers (e.g. set_handler) that only need a port’s id, name, and kind.

Shape

A bundle of typed external ports. Implementors expose their inlets/outlets in a stable order; inlets()/outlets() return the type-erased views the builder validates against. Cheap to clone (ports are id + name).

TimerHandler

Reacts to a stage timer firing; key is the timer’s string key. Installed via GraphStageLogic::set_timer_handler.

WireDsl

Shape extension methods for method-based graph wiring.

WireSpec

A graph wiring specification accepted by GraphBuilder::wire and GraphBuilder::try_wire.

Type Aliases

ImportedGraph