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¶

#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:

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

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