Class DiskPortrayalInstructionCache

Namespace

EncDotNet.S100.Pipelines.Vector.Caching

Assembly

EncDotNet.S100.Core.dll

Disk-backed IPortrayalInstructionCache: persists each prepared S-100 Part 9 display list as a sidecar file so the cold first open of a previously-portrayed dataset — including after a process restart — skips the portrayal run (for S-101 the ~1 s MoonSharp Lua execution).

public sealed class DiskPortrayalInstructionCache : IPortrayalInstructionCache

Inheritance

object

DiskPortrayalInstructionCache

Implements

IPortrayalInstructionCache

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The companion InMemoryPortrayalInstructionCache only helps re-opens within one session and is lost on restart; this implementation closes that gap by persisting the list to disk. The cache is correct only when the caller's key fully captures every portrayal input — see IPortrayalInstructionCache — which the S-101 processor ensures by folding the dataset content hash, the feature- and portrayal-catalogue content hashes, the engine/format stamp, and the mariner + ECDIS state into the key.

Robustness mirrors DiskPatternClipCache: any IO error, truncated / corrupt file, or FormatVersion mismatch is treated as a miss (the factory runs and overwrites); failures never propagate. Writes are atomic (temp file + move). The cache is bounded by a total-bytes cap with least-recently-used eviction (see DiskCacheBudget), and the directory is shared across every processor, so all members are thread-safe. Hits read and deserialize without a lock, so concurrent loads do not serialize on the cache.

Constructors

DiskPortrayalInstructionCache(string, long)

Creates a disk-backed display-list cache rooted at cacheDirectory.

public DiskPortrayalInstructionCache(string cacheDirectory, long maxBytes)

Parameters

cacheDirectory string

Directory under which sidecar files are stored. Created on first write if absent. Assumed private to this cache (the LRU sweep enumerates every *.dlist file in it).

maxBytes long

Soft upper bound, in bytes, on the total size of all persisted files. After a write that exceeds it, the least-recently-used files are evicted until the total is at or below this cap. Must be positive.

Exceptions

ArgumentException

cacheDirectory is null or empty.

ArgumentOutOfRangeException

maxBytes is not positive.

Properties

Hits

Number of GetOrCompute(string, Func<IReadOnlyList<DrawingInstruction>>) calls served from the cache (the portrayal run was skipped). Exposed for diagnostics and tests.

public long Hits { get; }

Property Value

long

MaxBytes

Soft upper bound, in bytes, on the total size of the persisted entries.

public long MaxBytes { get; }

Property Value

long

Misses

Number of GetOrCompute(string, Func<IReadOnlyList<DrawingInstruction>>) calls that ran the factory (cache miss). Exposed for diagnostics and tests.

public long Misses { get; }

Property Value

long

TotalBytes

The total size, in bytes, of the persisted entries. The first call reads the cache directory if no write has done so yet.

public long TotalBytes { get; }

Property Value

long

Methods

Contains(string)

Whether an entry is persisted for key. Checks only that the file exists: it neither reads nor validates the entry, and does not mark it used.

public bool Contains(string key)

Parameters

key string

A key as passed to GetOrCompute(string, Func<IReadOnlyList<DrawingInstruction>>).

Returns

bool

true when the entry's file exists.

GetOrCompute(string, Func<IReadOnlyList<DrawingInstruction>>)

Returns the cached drawing-instruction list for key, invoking factory to compute and store it on a miss.

public IReadOnlyList<DrawingInstruction> GetOrCompute(string key, Func<IReadOnlyList<DrawingInstruction>> factory)

Parameters

key string

An opaque key that fully identifies the portrayal inputs (see the type remarks). The same key must always map to the same instruction list.

factory Func<IReadOnlyList<DrawingInstruction>>

Runs the portrayal pipeline to produce the instruction list when the key is not cached. Only invoked on a miss.

Returns

IReadOnlyList<DrawingInstruction>

The drawing-instruction list, in the same order as produced by the pipeline (the order is significant: it is the renderer's final priority tie-breaker). On a disk-cache hit the returned instances are freshly deserialized but value-equivalent to the originals.

GetOrComputeAsync(string, Func<CancellationToken, ValueTask<IReadOnlyList<DrawingInstruction>>>, CancellationToken)

Async counterpart to GetOrCompute(string, Func<IReadOnlyList<DrawingInstruction>>). Used by callers that drive the portrayal pipeline asynchronously (the standard render path) so the factory can await instead of blocking.

public ValueTask<IReadOnlyList<DrawingInstruction>> GetOrComputeAsync(string key, Func<CancellationToken, ValueTask<IReadOnlyList<DrawingInstruction>>> factory, CancellationToken cancellationToken = default)

Parameters

key string

factory Func<CancellationToken, ValueTask<IReadOnlyList<DrawingInstruction>>>

cancellationToken CancellationToken

Returns

ValueTask<IReadOnlyList<DrawingInstruction>>