# Networks

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

## Building a network

```cpp
--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:

```cpp
// 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:

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

Or print a full report at any time:

```cpp
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:

```cpp
--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](error-handling.md).

## 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](static-network.md).