Class LogRing
The bounded tail of the log that the in-app panel reads from.
Inherited Members
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. |