KPN/docs/network.md

Networks

A Network wires nodes together at runtime using a builder chain.

Building a network

--8<-- "examples/01_hello_pipeline/main.cpp:network_build"

The builder chain:

Method	Purpose
.add(name, node)	Register a node; assigns its name
.connect(src, port, dst, port)	Wire one output port to one input port
.build()	Compute topological order; inject network callbacks
.start()	Start nodes in topological order
.stop()	Stop all nodes immediately
.shutdown()	Graceful drain: stop sources first, wait for channels to empty, then stop downstream

Port access

Ports are accessed by index or by name:

// By index
net.connect("src", src.output<0>(), "dst", dst.input<0>());

// By name (requires named ports)
--8<-- "examples/02_named_ports/main.cpp:named_port_network"

Diagnostics

Install a diagnostics handler to receive periodic snapshots of every node and channel:

--8<-- "examples/05_error_handling/main.cpp:diagnostics_handler"

Or print a full report at any time:

net.print_diagnostics();   // writes to stderr by default
net.print_diagnostics(std::cout);

Network-level event handler

Observe overflow and node-stop events across the entire network in one place:

--8<-- "examples/16_event_callbacks/main.cpp:network_event_handler"

NodeEvent is either NodeEvent::Overflow (item dropped on full channel) or NodeEvent::Closed (node stopped due to crash or closed upstream channel). See Error Handling & Events.

Shutdown

net.stop() halts immediately — all nodes stop in reverse topological order.

net.shutdown() drains gracefully: source nodes stop first; their output channels are polled until empty; then the next layer stops, and so on. This ensures no items are lost if downstream nodes are still consuming.

StaticNetwork

For zero-overhead compile-time topology, see Static Networks.