4bbc4589e7
The pathing and step-cache comments had accumulated as development notes rather
than documentation: internal phase jargon ("Tier 4", "the Phase-2 synthesizer"),
change narration aimed at a reviewer ("which the old ComputeStandingZ anchor
missed", "legacy behavior"), benchmark anecdotes ("benchmarked as near-optimal",
"a ~20 ns lookup"), and multi-paragraph blocks restating what the code says.
Rewritten to keep the rationale a reader cannot derive from the code - why the
source-Z guard cannot be loosened, why multis fall through, why the promotion gate
counts Finds instead of calls, why the fingerprint hashes files rather than the
live tile tables - and to drop the history that got us there.
Also corrects comments that had gone stale:
- CacheEvictionTimer and CacheStats documented a class named
StaticWalkabilityCache, which no longer exists; it is StepCache.
- StepCacheFile's header said "File layout v8" while FormatVersion is 9, and the
body called the current record layout "the v6 layout" throughout. The layout
descriptions are now unversioned, since they describe whatever FormatVersion
currently is.
- StepProbe.ComputeStandingZ claimed StepCache uses it to bake SourceZ. It hasn't
since the baker moved to the clearance-aware ComputeStandableSurfaceZs; only a
parity test calls it now.
Two small code changes came along with the comment work, both behavior-preserving:
_lazyReaders now uses a collection expression like its neighbours, and
TryLoadFromLazyReader collapses to an expression body once its inline comment moved
to the doc comment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
37 lines
1.5 KiB
C#
37 lines
1.5 KiB
C#
namespace Server.Engines.Pathing.Cache;
|
|
|
|
/// <summary>
|
|
/// Snapshot of <see cref="StepCache"/>'s counters, as returned by GetStats() and reported by
|
|
/// the [PathCacheStats command. Every counter is monotonic except ResidentChunks, and all of
|
|
/// them reset on Clear() — they count since the last clear, not since startup.
|
|
/// </summary>
|
|
public readonly struct CacheStats(
|
|
int residentChunks,
|
|
long hits,
|
|
long missesNotBuilt,
|
|
long missesDirtyRebuild,
|
|
long fallthroughMultiZ,
|
|
long fallthroughOffMap,
|
|
long fallthroughSourceZMismatch,
|
|
long fallthroughNotBuilt,
|
|
long fallthroughMulti,
|
|
long multiLocalHits,
|
|
long multiMaskCacheHits,
|
|
long evictionsByLruCap,
|
|
long buildsTotal
|
|
)
|
|
{
|
|
public readonly int ResidentChunks = residentChunks;
|
|
public readonly long Hits = hits;
|
|
public readonly long MissesNotBuilt = missesNotBuilt;
|
|
public readonly long MissesDirtyRebuild = missesDirtyRebuild;
|
|
public readonly long FallthroughMultiZ = fallthroughMultiZ;
|
|
public readonly long FallthroughOffMap = fallthroughOffMap;
|
|
public readonly long FallthroughSourceZMismatch = fallthroughSourceZMismatch;
|
|
public readonly long FallthroughNotBuilt = fallthroughNotBuilt;
|
|
public readonly long FallthroughMulti = fallthroughMulti;
|
|
public readonly long MultiLocalHits = multiLocalHits;
|
|
public readonly long MultiMaskCacheHits = multiMaskCacheHits;
|
|
public readonly long EvictionsByLruCap = evictionsByLruCap;
|
|
public readonly long BuildsTotal = buildsTotal;
|
|
}
|