Class LogRing

The bounded tail of the log that the in-app panel reads from.

Inheritance
LogRing
Namespace: MOSAIC.Diagnostics
Assembly: MOSAIC.dll
Syntax
public sealed class LogRing
Remarks

The panel is a tail view, not a transcript: the file is the complete record. So the ring keeps a fixed Capacity and simply overwrites, which is what bounds the memory cost of a long lab session no matter how loud a device gets.

Any number of threads may touch it. The steady state is two - the sink's single writer thread through Add(in LogEntry), the UI thread through CopyFrom(long, List<LogEntry>, int) - but a producer calls Add(in LogEntry) itself whenever the sink cannot take the entry: before initialisation, when no log folder could be created, once the sink's writer has given up for good, and once the sink has been shut down.

So Add(in LogEntry) is on a data thread's hot path. Every member that touches the shared state - Add(in LogEntry), CopyFrom(long, List<LogEntry>, int), Clear() and NextSequence - takes the same lock and holds it for no more than a bounded copy of at most max entries; Capacity needs no lock because it never changes after construction. Inside the lock there is no I/O and nothing unbounded, so an EMG thread can never end up waiting on the disk. It is not allocation-free, though: CopyFrom(long, List<LogEntry>, int) appends to the caller's list while holding the lock, so a list that has to grow allocates there. That is amortised and bounded by max, and a caller that cares can size its list once and never pay it again.

Constructors

LogRing()

Creates a ring of DefaultCapacity entries.

Declaration
public LogRing()

LogRing(int)

Creates a ring of capacity entries (at least one).

Declaration
public LogRing(int capacity)
Parameters
Type Name Description
int capacity

Number of entries to retain before overwriting the oldest.

Fields

DefaultCapacity

Entries retained for the panel. Roughly an hour of ordinary lifecycle logging.

Declaration
public const int DefaultCapacity = 2000
Field Value
Type Description
int

_appended

Declaration
private long _appended
Field Value
Type Description
long

_buffer

Declaration
private readonly LogEntry[] _buffer
Field Value
Type Description
LogEntry[]

_gate

Declaration
private readonly object _gate
Field Value
Type Description
object

_retained

Declaration
private int _retained
Field Value
Type Description
int

_writeIndex

Declaration
private int _writeIndex
Field Value
Type Description
int

Properties

Capacity

Number of entries retained before the oldest is overwritten.

Declaration
public int Capacity { get; }
Property Value
Type Description
int

NextSequence

The cursor the next appended entry will carry. A reader that starts here sees only entries added from now on, which is how a freshly opened panel avoids replaying history it was never asked for.

Declaration
public long NextSequence { get; }
Property Value
Type Description
long
Remarks

This is the ring's own append counter, not Sequence: producers hand out sequence numbers before queueing, so two entries can reach the ring in the opposite order to their ids. A cursor derived from the id would then skip the later arrival or replay it.

Methods

Add(in LogEntry)

Appends one entry, overwriting the oldest when full. Called from the sink's writer thread, and directly from a producer whenever the sink cannot get the entry to the file - it is absent, its writer has stopped, or its channel has been completed at shutdown. A merely full queue is not one of those: the channel drops its oldest entry and accepts the write, so overflow is counted rather than rerouted here.

Declaration
internal void Add(in LogEntry entry)
Parameters
Type Name Description
LogEntry entry

The entry to retain.

Clear()

Drops every retained entry. The file is untouched.

Declaration
public void Clear()
Remarks

The append counter keeps running, so a reader holding an old cursor simply finds nothing left to copy rather than being replayed the entries that follow.

CopyFrom(long, List<LogEntry>, int)

Copies every retained entry appended at or after fromSequence into into, appending at most max, and returns the cursor to pass on the next call.

Declaration
public long CopyFrom(long fromSequence, List<LogEntry> into, int max)
Parameters
Type Name Description
long fromSequence

Cursor from the previous call, or 0 for everything retained.

List<LogEntry> into

Destination list. Entries are appended; existing content is left alone.

int max

Upper bound on entries copied, so one burst cannot stall the UI thread.

Returns
Type Description
long

The next cursor. Unchanged when nothing was copied. When the caller has fallen further behind than Capacity, the copy silently resumes at the oldest retained entry - the gap is visible in the file, and stalling the panel to preserve it would help nobody.

Search documentation

Start typing to search the documentation.