43 lines
1.4 KiB
Markdown
43 lines
1.4 KiB
Markdown
# 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.
|