# Shared Resources

`SharedResource<T>` arbitrates exclusive access to a resource (ONNX session, CUDA stream, serial port) across multiple nodes using a priority-based waiter queue with starvation prevention.

## Usage

```cpp
#include <kpn/shared_resource.hpp>
using namespace kpn;

SharedResource<OnnxSession> model(session_args...);

static cv::Mat run_inference(cv::Mat frame) {
    // Acquires the model; releases automatically on scope exit.
    auto guard = model.acquire_balanced(in_channel, out_channel);
    return guard->Run(frame);
}
```

## Acquire modes

| Method | Priority |
|---|---|
| `acquire()` | Equal (fair FIFO) |
| `acquire(fn)` | Custom — `fn()` returns `float` in `[0, 1]` |
| `acquire_balanced(in_ch, out_ch)` | `input_fill × output_headroom` — highest urgency wins |

`acquire_balanced` favours nodes with full input queues and empty output queues — the node that has the most work to do and nowhere to stall wins the resource next.

## Starvation prevention

Each waiter's effective score grows with elapsed wait time (`0.05` per second by default), ensuring a low-priority node eventually gets served regardless of how frequently higher-priority nodes compete.

## Diagnostics

Register with the network for snapshot reporting:

```cpp
net.register_resource("model", &model);
```

The diagnostics table then shows acquisition count, mean wait time, and current waiter count.