diagnostics: add STEP-099 render source readiness audit

This commit is contained in:
tei
2026-10-06 15:15:12 +09:00
parent e8b451fe70
commit 8a5214d92d
13 changed files with 915 additions and 9 deletions

View File

@@ -65,6 +65,50 @@ RendererObserver& nullObserver() {
return observer;
}
const char* sourceTypeText(style::SourceType type) noexcept {
switch (type) {
case style::SourceType::Vector: return "vector";
case style::SourceType::Raster: return "raster";
case style::SourceType::RasterDEM: return "raster-dem";
case style::SourceType::GeoJSON: return "geojson";
case style::SourceType::Video: return "video";
case style::SourceType::Annotations: return "annotations";
case style::SourceType::Image: return "image";
case style::SourceType::CustomVector: return "customvector";
case style::SourceType::RasterArray: return "raster-array";
}
return "unknown";
}
const char* tileOperationText(TileOperation op) noexcept {
switch (op) {
case TileOperation::RequestedFromCache: return "RequestedFromCache";
case TileOperation::RequestedFromNetwork: return "RequestedFromNetwork";
case TileOperation::LoadFromNetwork: return "LoadFromNetwork";
case TileOperation::LoadFromCache: return "LoadFromCache";
case TileOperation::StartParse: return "StartParse";
case TileOperation::EndParse: return "EndParse";
case TileOperation::Error: return "Error";
case TileOperation::Cancelled: return "Cancelled";
case TileOperation::NullOp: return "NullOp";
}
return "Unknown";
}
const char* readinessEventType(RetainedUnderlayReason reason) noexcept {
switch (reason) {
case RetainedUnderlayReason::SourceMutation: return "SourceMutation";
case RetainedUnderlayReason::TileMutation: return "TileMutation";
case RetainedUnderlayReason::ImageMutation: return "ImageMutation";
case RetainedUnderlayReason::GlyphMutation: return "GlyphMutation";
case RetainedUnderlayReason::StyleMutation: return "StyleMutation";
case RetainedUnderlayReason::LayerMutation:
case RetainedUnderlayReason::LayerGroupMutation: return "LayerMutation";
case RetainedUnderlayReason::ContextReset: return "ContextReset";
default: return "OtherMutation";
}
}
class RenderTreeImpl final : public RenderTree {
public:
RenderTreeImpl(std::unique_ptr<RenderTreeParameters> parameters_,
@@ -153,9 +197,89 @@ RenderOrchestrator::~RenderOrchestrator() {
threadPool.waitForEmpty();
}
void RenderOrchestrator::advanceRetainedUnderlayContentRevision(RetainedUnderlayReason reason) noexcept {
void RenderOrchestrator::recordReadinessMutation(const char* eventType,
RetainedUnderlayReason reason,
const std::optional<std::string>& sourceId,
const std::string& tileAction) noexcept {
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
const auto sequence = ++readinessEventSequence;
lastReadinessMutation.sequence = sequence;
lastReadinessMutation.contentRevision = retainedUnderlayContentRevision.load(std::memory_order_acquire);
lastReadinessMutation.eventType = eventType;
lastReadinessMutation.reason = retainedUnderlayReasonText(reason);
lastReadinessMutation.sourceId = sourceId;
lastReadinessMutation.affectedSegmentIndices.clear();
lastReadinessMutation.dependencyScope = sourceId ? "unresolved-until-snapshot" : "shared/global/unknown";
if (sourceId) {
auto& state = sourceReadinessEvents[*sourceId];
state.lastMutationReason = retainedUnderlayReasonText(reason);
if (reason == RetainedUnderlayReason::SourceMutation) state.lastSourceMutationSequence = sequence;
if (reason == RetainedUnderlayReason::TileMutation) state.lastTileChangedSequence = sequence;
if (!tileAction.empty()) {
state.lastTileActionSequence = sequence;
state.lastTileAction = tileAction;
}
}
} catch (...) {
// Diagnostic recording is best-effort and must not escape into renderer mutation paths.
}
}
void RenderOrchestrator::advanceRetainedUnderlayContentRevision(
RetainedUnderlayReason reason,
const std::optional<std::string>& sourceId) noexcept {
retainedUnderlayContentReason.store(reason, std::memory_order_release);
retainedUnderlayContentRevision.fetch_add(1, std::memory_order_acq_rel);
recordReadinessMutation(readinessEventType(reason), reason, sourceId);
}
RendererReadinessDiagnostics RenderOrchestrator::buildReadinessDiagnostics(bool styleLoaded,
bool spriteLoaded) const {
RendererReadinessDiagnostics result;
result.styleLoaded = styleLoaded;
result.imageManagerLoaded = imageManager->isLoaded();
result.spriteLoaded = spriteLoaded;
result.contentRevision = retainedUnderlayContentRevision.load(std::memory_order_acquire);
std::unordered_map<std::string, SourceReadinessEventState> sourceEvents;
{
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
// Snapshot-only: do not prune or otherwise mutate diagnostic history from a query path.
// Entries for sources no longer present are naturally ignored below because we enumerate
// the current renderSources set and only look up matching ids.
sourceEvents = sourceReadinessEvents;
result.lastMutation = lastReadinessMutation;
}
result.renderOrchestratorLoaded = result.imageManagerLoaded;
result.sources.reserve(renderSources.size());
for (const auto& [sourceId, renderSource] : renderSources) {
const auto stats = renderSource->getReadinessDiagnostics();
RenderSourceReadinessDiagnostics source;
source.sourceId = sourceId;
source.sourceType = sourceTypeText(renderSource->baseImpl->type);
source.enabled = renderSource->isEnabled();
source.isLoaded = renderSource->isLoaded();
source.tileBacked = stats.tileBacked;
source.tileCount = stats.tileCount;
source.incompleteTileCount = stats.incompleteTileCount;
source.loadedTileCount = stats.loadedTileCount;
source.hasFadingTiles = stats.hasFadingTiles;
result.hasFadingTiles = result.hasFadingTiles || stats.hasFadingTiles;
result.renderOrchestratorLoaded = result.renderOrchestratorLoaded && source.isLoaded;
if (const auto it = sourceEvents.find(sourceId); it != sourceEvents.end()) {
source.lastSourceMutationSequence = it->second.lastSourceMutationSequence;
source.lastTileChangedSequence = it->second.lastTileChangedSequence;
source.lastTileActionSequence = it->second.lastTileActionSequence;
source.lastTileAction = it->second.lastTileAction;
source.lastMutationReason = it->second.lastMutationReason;
}
result.sources.push_back(std::move(source));
}
std::ranges::sort(result.sources, {}, &RenderSourceReadinessDiagnostics::sourceId);
return result;
}
void RenderOrchestrator::markContextLost() {
@@ -361,6 +485,15 @@ std::unique_ptr<RenderTree> RenderOrchestrator::createRenderTree(
const SourceDifference sourceDiff = diffSources(sourceImpls, updateParameters->sources);
if (!sourceDiff.added.empty() || !sourceDiff.removed.empty() || !sourceDiff.changed.empty()) {
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
for (const auto& entry : sourceDiff.added) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
for (const auto& entry : sourceDiff.removed) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
for (const auto& entry : sourceDiff.changed) {
recordReadinessMutation("SourceMutation", RetainedUnderlayReason::SourceMutation, entry.first);
}
}
sourceImpls = updateParameters->sources;
@@ -519,7 +652,17 @@ std::unique_ptr<RenderTree> RenderOrchestrator::createRenderTree(
addChanges(changes);
}
// Readiness is sampled for diagnostics only. Preserve the renderer's formal load gate.
renderTreeParameters->loaded = updateParameters->styleLoaded && isLoaded();
if (updateParameters->retainedUnderlayState) {
try {
auto readinessDiagnostics =
buildReadinessDiagnostics(updateParameters->styleLoaded, updateParameters->spriteLoaded);
updateParameters->retainedUnderlayState->recordRendererReadiness(std::move(readinessDiagnostics));
} catch (...) {
// A failed diagnostic snapshot must not affect the render tree or its formal loaded gate.
}
}
if (!isMapModeContinuous && !renderTreeParameters->loaded) {
return nullptr;
}
@@ -835,7 +978,7 @@ void RenderOrchestrator::setFeatureState(const std::string& sourceID,
if (RenderSource* renderSource = getRenderSource(sourceID)) {
renderSource->setFeatureState(sourceLayerID, featureID, state);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation, sourceID);
}
}
@@ -858,7 +1001,7 @@ void RenderOrchestrator::removeFeatureState(const std::string& sourceID,
if (RenderSource* renderSource = getRenderSource(sourceID)) {
renderSource->removeFeatureState(sourceLayerID, featureID, stateKey);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::SourceMutation, sourceID);
}
}
@@ -1080,6 +1223,13 @@ void RenderOrchestrator::clearData() {
imageManager->clear();
glyphManager->evict(fontStacks(*layerImpls));
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
sourceReadinessEvents.clear();
lastReadinessMutation = {};
} catch (...) {
// Keep renderer style cleanup independent from optional diagnostic history cleanup.
}
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::StyleMutation);
}
@@ -1295,10 +1445,10 @@ void RenderOrchestrator::onTileError(RenderSource& source, const OverscaledTileI
observer->onResourceError(error);
}
void RenderOrchestrator::onTileChanged(RenderSource&, const OverscaledTileID&) {
void RenderOrchestrator::onTileChanged(RenderSource& source, const OverscaledTileID&) {
MLN_TRACE_FUNC();
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::TileMutation);
advanceRetainedUnderlayContentRevision(RetainedUnderlayReason::TileMutation, source.baseImpl->id);
observer->onInvalidate();
}
@@ -1306,6 +1456,15 @@ void RenderOrchestrator::onTileAction(RenderSource&,
TileOperation op,
const OverscaledTileID& id,
const std::string& sourceID) {
try {
std::lock_guard<std::mutex> lock(readinessDiagnosticsMutex);
const auto sequence = ++readinessEventSequence;
auto& state = sourceReadinessEvents[sourceID];
state.lastTileActionSequence = sequence;
state.lastTileAction = tileOperationText(op);
} catch (...) {
// Tile action observation is best-effort; always forward the original observer callback.
}
observer->onTileAction(op, id, sourceID);
}