Class LogFileSink
The bounded queue, the single background writer, the rolling file and its retention policy.
Assembly: MOSAIC.dll
Syntax
internal sealed class LogFileSink : IAsyncDisposable
Constructors
LogFileSink(string)
Opens the first file and starts the writer task. Never throws.
Declaration
internal LogFileSink(string directory)
Parameters
| Type |
Name |
Description |
| string |
directory |
Folder to write into. Must already exist.
|
Fields
DropReportIntervalMs
Declaration
private const int DropReportIntervalMs = 1000
Field Value
FileEncoding
Declaration
private static readonly UTF8Encoding FileEncoding
Field Value
FlushIntervalMs
Longest a written line may sit unflushed.
Declaration
internal const int FlushIntervalMs = 250
Field Value
MaxFileBytes
File size at which the writer rolls over to the next file.
Declaration
internal const long MaxFileBytes = 8388608
Field Value
MaxRetainedFiles
Log files kept in the folder; older ones are deleted when a new run starts.
Declaration
internal const int MaxRetainedFiles = 10
Field Value
MaxWriterRestarts
Declaration
private const int MaxWriterRestarts = 3
Field Value
NewLineByteCount
Declaration
private static readonly int NewLineByteCount
Field Value
QueueCapacity
Entries buffered before the oldest starts being dropped.
Declaration
internal const int QueueCapacity = 4096
Field Value
WriterRestartDelayMs
Declaration
private const int WriterRestartDelayMs = 500
Field Value
_baseName
Declaration
private readonly string _baseName
Field Value
_bytesWritten
Declaration
private long _bytesWritten
Field Value
_channel
Declaration
private readonly Channel<LogEntry> _channel
Field Value
_cts
Declaration
private readonly CancellationTokenSource _cts
Field Value
_currentPath
Declaration
private volatile string? _currentPath
Field Value
_directory
Declaration
private readonly string _directory
Field Value
_disposed
Declaration
Field Value
_dropped
Declaration
Field Value
_fileGate
Declaration
private readonly SemaphoreSlim _fileGate
Field Value
_lastDropReportTicks
Declaration
private long _lastDropReportTicks
Field Value
_lastFlushTicks
Declaration
private long _lastFlushTicks
Field Value
_reportedDropped
Declaration
private long _reportedDropped
Field Value
_ring
Declaration
private readonly LogRing _ring
Field Value
_rotation
Declaration
Field Value
_stream
Declaration
private FileStream? _stream
Field Value
_unflushed
Declaration
Field Value
_writer
Declaration
private StreamWriter? _writer
Field Value
_writerStopped
Declaration
private int _writerStopped
Field Value
_writerTask
Declaration
private readonly Task _writerTask
Field Value
Properties
CurrentPath
Path of the file currently being appended to, or null if none could be opened.
Declaration
internal string? CurrentPath { get; }
Property Value
Dropped
Entries the queue has dropped because it was full.
Declaration
internal long Dropped { get; }
Property Value
WriterStopped
True once the writer task has given up: the queue is no longer being drained, so nothing new
reaches the log file until the next Initialize(). The ring and the panel do
keep filling - Log treats a stopped writer as a refusal and routes the entry to
the ring instead. Surfaced to the UI as WriterStopped.
Declaration
internal bool WriterStopped { get; }
Property Value
Methods
Close()
Declaration
DisposeAsync()
Stops the writer, drains what is left and closes the file. Never throws.
Declaration
public ValueTask DisposeAsync()
Returns
DrainLoop()
Declaration
Returns
FlushCritical(TimeSpan)
Drains the queue and flushes the file on the CALLING thread, giving up after
timeout rather than deadlocking a dying process.
Declaration
internal void FlushCritical(TimeSpan timeout)
Parameters
| Type |
Name |
Description |
| TimeSpan |
timeout |
How long to wait for the writer to release the file.
|
FlushFile()
Declaration
GuardedFlushAsync()
Declaration
private Task GuardedFlushAsync()
Returns
Open()
Declaration
Prune(int)
Deletes the oldest files until at most keep remain.
Declaration
private void Prune(int keep)
Parameters
| Type |
Name |
Description |
| int |
keep |
|
ReportDrops()
Turns a full queue into a visible line rather than a silent gap. Caller holds the file gate.
Declaration
private void ReportDrops()
ReportInternalFailure(Exception)
The logger's own failure path. It must never call Log's write path: a disk
failure would then log an error, which would fail, which would log an error.
NoteInternalFailure(string, Exception) only stores a counter and a string.
Declaration
private static void ReportInternalFailure(Exception ex)
Parameters
ReportInternalFailure(string)
The logger's own failure path. It must never call Log's write path: a disk
failure would then log an error, which would fail, which would log an error.
NoteInternalFailure(string, Exception) only stores a counter and a string.
Declaration
private static void ReportInternalFailure(string detail)
Parameters
| Type |
Name |
Description |
| string |
detail |
|
Rotate()
Declaration
TryEnqueue(in LogEntry)
Hands an entry to the writer. One non-blocking channel write and nothing else - no lock, no
allocation, no disk - which is what makes it safe to call from inside a device lock on a
notification thread.
Declaration
internal bool TryEnqueue(in LogEntry entry)
Parameters
| Type |
Name |
Description |
| LogEntry |
entry |
The entry to write.
|
Returns
| Type |
Description |
| bool |
False only once the sink has been shut down.
|
WriteBacklog(LogEntry[], int)
Appends entries captured before this sink existed. File only: Log has already
put them in the ring, and adding them again would show the panel every line twice.
Declaration
internal void WriteBacklog(LogEntry[] entries, int count)
Parameters
| Type |
Name |
Description |
| LogEntry[] |
entries |
Buffered entries, oldest first.
|
| int |
count |
How many leading elements of entries to write.
|
WriteEntry(in LogEntry)
Writes one entry to the ring and the file. Caller holds the file gate.
Declaration
private void WriteEntry(in LogEntry entry)
Parameters
WriteLine(in LogEntry)
Writes one entry to the file only. Caller holds the file gate.
Declaration
private void WriteLine(in LogEntry entry)
Parameters
WriterLoop()
Runs the drain continuously. Transient faults are retried; a persistent fault leaves
WriterStopped set and records a description in LastInternalError.
Declaration
private Task WriterLoop()
Returns
Implements