Class TraceFileCacheWriter

Namespace

Typhon.Profiler

Assembly

Typhon.Profiler.dll

Writes a .typhon-trace-cache sidecar file. Owns the underlying stream; not thread-safe.

public sealed class TraceFileCacheWriter : IDisposable

Inheritance

object

TraceFileCacheWriter

Implements

IDisposable

Inherited Members

object.GetType()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

Write protocol: construct the writer (reserves header + section-table placeholder at stream offsets 0..271), then call BeginSection(CacheSectionId) / Write* to emit each section in turn, then call Finalize(in CacheHeader) with the final header (fingerprint filled in by the builder). The writer rewinds once at finalize to patch the header + section table; the stream must support seek.

Sections can be emitted in any order. The writer records each section's byte range in Typhon.Profiler.TraceFileCacheWriter._sections as it goes and stitches the final CacheSectionId → offset/length table at finalize time.

Constructors

TraceFileCacheWriter(Stream)

Opens a cache writer over stream, reserving header + section-table space so the first section write lands at SectionsStartOffset. The stream must be seekable — the writer rewinds once at finalize to patch the header and section table. The writer takes ownership and disposes it in Dispose().

public TraceFileCacheWriter(Stream stream)

Parameters

stream Stream

Seekable, writable output stream for the .typhon-trace-cache file.

Exceptions

ArgumentNullException

stream is null.

ArgumentException

stream is not seekable.

Fields

MaxSections

Number of distinct section slots reserved in the table. Bumping this requires re-reserving more placeholder space — the section table sits at a fixed offset (128) and the subsequent SectionsStartOffset derives from this constant, so changing it shifts where the very first section is written. v12 (#311) bumped this from 8 → 16 to accommodate the four new sections (SystemTickSummaries, QueueTickSummaries, PostTickSummaries, QueueNameTable) plus headroom for future v13/v14 extensions without another invalidation pass.

public const int MaxSections = 16

Field Value

int

SectionsStartOffset

Fixed offset where section writes begin. Header (128) + section table (MaxSections × 24 = 192) = 320. Kept 8-aligned so subsequent struct writes are naturally aligned.

public const int SectionsStartOffset = 512

Field Value

int

Properties

CurrentOffset

Current byte offset in the cache file. Useful for capturing chunk offsets before appending their compressed payload.

public long CurrentOffset { get; }

Property Value

long

Methods

AppendLz4Chunk(ReadOnlySpan<byte>)

LZ4-compress uncompressedRecords and append the compressed bytes to the current section (which must be FoldedChunkData). Returns the byte offset and lengths needed to populate a matching ChunkManifestEntry.

public (long CacheOffset, uint CompressedLength, uint UncompressedLength) AppendLz4Chunk(ReadOnlySpan<byte> uncompressedRecords)

Parameters

uncompressedRecords ReadOnlySpan<byte>

Returns

(long CacheOffset, uint CompressedLength, uint UncompressedLength)

BeginSection(CacheSectionId)

Start a new section. If a section was already in progress, it is closed and its [offset, length) is recorded in the section table.

public void BeginSection(CacheSectionId id)

Parameters

id CacheSectionId

Dispose()

Disposes the writer and the underlying stream. If Finalize(in CacheHeader) was never called the file is left unfinalized (callers may treat it as a build-in-progress artifact). Idempotent.

public void Dispose()

Finalize(in CacheHeader)

Finalize the cache file: closes any in-progress section, writes the section table at offset 128, writes the final header (including the caller's pre-computed fingerprint) at offset 0. The stream is positioned at EOF on return.

public void Finalize(in CacheHeader header)

Parameters

header CacheHeader

Write(ReadOnlySpan<byte>)

Raw bytes appended to the current section.

public void Write(ReadOnlySpan<byte> bytes)

Parameters

bytes ReadOnlySpan<byte>

WriteArray<T>(ReadOnlySpan<T>)

Write an array of blittable structs to the current section, packed contiguously.

public void WriteArray<T>(ReadOnlySpan<T> values) where T : unmanaged

Parameters

values ReadOnlySpan<T>

Type Parameters

T

WriteQueueNameTable(IReadOnlyDictionary<ushort, string>)

Write the v12 queue-name intern table — count u16 + entries of (u16 queueId, shortString name). Null or empty input emits a zero count and returns. Used by QueueNameTable.

public void WriteQueueNameTable(IReadOnlyDictionary<ushort, string> queueIdToName)

Parameters

queueIdToName IReadOnlyDictionary<ushort, string>

WriteSpanNameTable(IReadOnlyDictionary<int, string>)

Write the source file's span-name table (count u16 + entries of (u16 id, shortString name)). Null or empty input emits a zero count.

public void WriteSpanNameTable(IReadOnlyDictionary<int, string> spanNames)

Parameters

spanNames IReadOnlyDictionary<int, string>

WriteStruct<T>(in T)

Write a single blittable struct to the current section.

public void WriteStruct<T>(in T value) where T : unmanaged

Parameters

value T

Type Parameters

T