[−][src]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.