68 lines
2.0 KiB
Markdown
68 lines
2.0 KiB
Markdown
# 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).
|