# scroll-ring
Structures for MPSC text streaming
The goal of the data structure provided by this crate is to cater for the needs of stdout-style
text streaming over a lossy network, which results in thee requirements:
* store a byte data stream in a no-std/no-alloc buffer,
* be multi-producer (so that threads or even signals/interrupts can write to it),
* never block (calls may take O(n) time for the processed data, but even with much reading and
writing it mustn't take significantly longer -- ideally constant-time, but given atomics are
generally not constan-time, maybe "as fast as the atomics are"?),
* not interleave contiguous writes,
* not lose any writes (it's OK to admit overflows, but keep track of how many bytes overflew),
* keep old data around for as long as possible until it is overwritten,
* offer a reader a chance to get a reasonable chunk of data even when it's way too slow for the
current writes (think taking a snapshot of data scolling by), and
* overflow as little as possible.
Overflowing data may not even hit the buffer, for example when a slice larger than the buffer
is written, or when (large amounts of) data is to be written while a read happens, or while a
write from a slow process happens -- either way, the written bytes are counted, they're just
not available for reading (just as they would have been if the reader were merely too slow).
This is the minimal implementation that solely on "overflow as little as possible" to get a
waaaay easier implementation. Better options are:
* A perfect implementation would have atomics everywhere, and as long as there are no reads (or
no writes from threads with such low priority that higher priority writes wrap around before
the low priority write is done memcpy'ing), there would be no overflow. That'd be ideal, but
is really hard.
* An intermediate implementation would allow parallel writes, but have a brief period of
locking the administrative part of the data structure when operations start and stop. (Thus,
overflows might happen merely because an interrupt triggers at an inopportune time).
Both these versions would probably need a bitfield of valid bytes (or a list of busy
writers), because due to variable thread priorities concurrent writes don't finish in the
opposite order of being started.
* What is currently provided is about the dumbest possible version. For the whole duration of
reading or writing, the data structure stays locked, and any overflows are recorded into an
atomic field next to the locked structure.
The [ringbuf] data structures are used in single-threaded mode here; there is a
multi-threaded mode that could go some way implementing the others.
License: MIT OR Apache-2.0