Function delog::try_enqueue

pub unsafe fn try_enqueue(
    delogger: impl Delogger,
    record: &Record<'_>
) -> Result<(), ()>

The fallible “write to circular buffer” method. Marked unsafe to discourage use!

Safety

Unfortunately exposed for all to see, as the delog! macro needs access to it to implement the logger at call site. Hence marked as unsafe.

This implementation needs some HEAVY testing. It is unsound on PC, where the OS can schedule threads in any manner, but assumed to be sound in ARM Cortex-M NVIC situations, where interrupts are “nested”, in the sense that one may be interrupted, then the interrupter can, …, then the interrupter hands back control, …, and finally the original caller of this function regains control.

In this situation, we keep track of three counters (read, written, claimed), with invariants read <= written <= claimed. Each writer pessimistically gauges sufficient capacity for its log by checking claimed + size <= read + capacity, accounting for the wraparound. If so, the writer atomically advances the claim counter, and starts copying its data in this newly claimed space. At the end, it is the duty of the “first” caller to advance the written counter to the correct state.