Add a performance tracing system (FrameTimings) and fix a big that would cause 6-second stalls

This commit is contained in:
James Babcock committed 2026-07-04 12:20:13 -07:00
1 parent 971b04f677
commit 630b511d32
11 files changed
+786 -72

No files matched your search

+96 -37
View File
@@ -3,6 +3,7 @@ import { EventSourceType, EventSourceTypeName, OsEventTypeList, OsEventTypeName
import { loadDeviceAddresses } from "./device-addresses";
import { ensureBlePermissions, ensureVoicePermissions } from "./android-permissions";
import { FaceclawCommunicatorBridge, type FrameMetrics, type RawInputEvent } from "../native/faceclaw-communicator";
import * as frameTimings from "../native/frame-timings";
import { startForegroundNotification, stopForegroundNotification, updateForegroundNotification } from "../native/foreground-service";
import { mediaControllerBridge } from "../native/media-controller";
import { nightscoutBridge } from "../native/nightscout-bridge";
@@ -141,6 +142,7 @@ class DashboardController {
private renderInProgress = false;
private renderQueued = false;
private queuedRenderReason: "initial" | "interval" = "interval";
private queuedFrameId = 0;
private lastForegroundNotificationUpdateAtMs = 0;
private lastConnectedPreviewUpdateAtMs = 0;
private connectedPreviewUpdateSeq = 0;
@@ -532,32 +534,59 @@ class DashboardController {
this.updateDisplayPreviewFromImage(image);
}
private async requestRender(reason: "initial" | "interval"): Promise<void> {
/**
* Serialize renders; frameId identifies the input event or timer tick that
* asked for this render (one is started here for callers that don't have
* one). Ownership of the frame passes to renderDashboard and then to the
* Java side; requests that coalesce into an already-queued render finish
* immediately as discarded. When coalescing we keep the oldest waiting frame
* so measured latency reflects the worst-served request.
*/
private async requestRender(reason: "initial" | "interval", frameId?: number): Promise<void> {
const newFrameId = frameId ?? frameTimings.startFrame(`render:${reason}`);
this.queuedRenderReason = this.queuedRenderReason === "initial" ? "initial" : reason;
if (this.renderInProgress) {
this.renderQueued = true;
if (this.renderQueued && this.queuedFrameId > 0) {
frameTimings.finishFrame(newFrameId, `discarded: coalesced into frame#${this.queuedFrameId}`);
} else {
this.renderQueued = true;
this.queuedFrameId = newFrameId;
frameTimings.logFrame(newFrameId, "render queued behind in-progress render");
}
return;
}
this.renderInProgress = true;
let frameToRender = newFrameId;
try {
do {
while (true) {
const nextReason = this.queuedRenderReason;
this.renderQueued = false;
this.queuedRenderReason = "interval";
await this.renderDashboard(nextReason);
} while (this.renderQueued);
try {
await this.renderDashboard(nextReason, frameToRender);
} catch (error) {
frameTimings.finishFrame(frameToRender, `discarded: render failed: ${this.formatError(error)}`);
throw error;
}
if (!this.renderQueued || this.queuedFrameId <= 0) break;
frameToRender = this.queuedFrameId;
this.queuedFrameId = 0;
}
} finally {
this.renderInProgress = false;
}
}
private async renderDashboard(reason: "initial" | "interval"): Promise<void> {
private async renderDashboard(reason: "initial" | "interval", frameId: number): Promise<void> {
console.log("renderDashboard", reason);
frameTimings.logFrame(frameId, `renderDashboard start (${reason})`);
const paintStartedAtMs = Date.now();
const image = drawDashboard();
const image = frameTimings.span(frameId, "paint", () =>
frameTimings.runWithFrame(frameId, () => drawDashboard()),
);
const paintMs = Date.now() - paintStartedAtMs;
const fingerprint = image.fingerprint();
const fingerprint = frameTimings.span(frameId, "fingerprint", () => image.fingerprint());
const updatePreviewAfterTransmit = this.phase === "connected";
if (!updatePreviewAfterTransmit) {
this.updateDisplayPreviewFromImage(image);
@@ -567,14 +596,22 @@ class DashboardController {
await this.communicator.setG2ScreenOn(true);
}
console.log("submitDashboardImage");
await this.communicator.submitDashboardImage(image.to8bppBuffer(), image.width, image.height, fingerprint, paintMs);
await this.communicator.waitForNextFrameMetrics(FRAME_TRANSMIT_BACKPRESSURE_TIMEOUT_MS);
const buffer = frameTimings.span(frameId, "to8bpp", () => image.to8bppBuffer());
// The Java side owns the frame from here: it finishes it on last-packet
// ack, dedup, supersede, or timeout.
await this.communicator.submitDashboardImage(buffer, image.width, image.height, fingerprint, paintMs, frameId);
const outcome = await this.communicator.waitForFrameFinished(frameId, FRAME_TRANSMIT_BACKPRESSURE_TIMEOUT_MS);
if (outcome === null) {
frameTimings.logFrame(frameId, "transmit backpressure wait timed out; render loop continuing");
}
if (!dashboardState.screenOn) {
await this.communicator.setG2ScreenOn(false);
}
if (updatePreviewAfterTransmit) {
await this.updateConnectedDisplayPreviewFromImage(image);
}
} else {
frameTimings.finishFrame(frameId, "discarded: no communicator, preview only");
}
this.updateConnectedForegroundNotification();
@@ -585,36 +622,53 @@ class DashboardController {
}
private async handleInputEvent(event: RawInputEvent): Promise<void> {
await receiveInput(event);
if (event.kind === "sys-event") {
this.lastSys = `${sourceName(event.eventSource)}/${eventName(event.eventType)}`;
this.appendLog(`sys-event ${this.lastSys}`);
if (
event.eventType === OsEventTypeList.FOREGROUND_EXIT_EVENT ||
event.eventType === OsEventTypeList.ABNORMAL_EXIT_EVENT ||
event.eventType === OsEventTypeList.SYSTEM_EXIT_EVENT
) {
this.appendLog("display state invalidated by firmware exit event");
const frameId =
event.frameId > 0 ? event.frameId : frameTimings.startFrame(`input:${event.kind} (untracked source)`);
frameTimings.logFrame(frameId, `TS input handler start: ${event.kind} ${eventName(event.eventType)}`);
let renderRequested = false;
try {
frameTimings.spanStart(frameId, "handle-input");
try {
await receiveInput(event);
} finally {
frameTimings.spanEnd(frameId, "handle-input");
}
if (event.eventSource === EventSourceType.TOUCH_EVENT_FROM_RING) {
this.lastInput = eventName(event.eventType);
}
await this.requestRender("interval");
return;
}
if (event.kind === "sys-event") {
this.lastSys = `${sourceName(event.eventSource)}/${eventName(event.eventType)}`;
this.appendLog(`sys-event ${this.lastSys}`);
if (event.kind === "text-click" && isDashboardContainerName(event.containerName)) {
if (
event.eventType === OsEventTypeList.SCROLL_TOP_EVENT ||
event.eventType === OsEventTypeList.SCROLL_BOTTOM_EVENT
) {
this.lastSys = `TEXT/${eventName(event.eventType)}`;
this.lastInput = `TEXT_${eventName(event.eventType)}`;
this.appendLog(`text-event ${this.lastSys}`);
await this.requestRender("interval");
if (
event.eventType === OsEventTypeList.FOREGROUND_EXIT_EVENT ||
event.eventType === OsEventTypeList.ABNORMAL_EXIT_EVENT ||
event.eventType === OsEventTypeList.SYSTEM_EXIT_EVENT
) {
this.appendLog("display state invalidated by firmware exit event");
}
if (event.eventSource === EventSourceType.TOUCH_EVENT_FROM_RING) {
this.lastInput = eventName(event.eventType);
}
renderRequested = true;
await this.requestRender("interval", frameId);
return;
}
if (event.kind === "text-click" && isDashboardContainerName(event.containerName)) {
if (
event.eventType === OsEventTypeList.SCROLL_TOP_EVENT ||
event.eventType === OsEventTypeList.SCROLL_BOTTOM_EVENT
) {
this.lastSys = `TEXT/${eventName(event.eventType)}`;
this.lastInput = `TEXT_${eventName(event.eventType)}`;
this.appendLog(`text-event ${this.lastSys}`);
renderRequested = true;
await this.requestRender("interval", frameId);
}
}
} finally {
if (!renderRequested) {
frameTimings.finishFrame(frameId, "discarded: input did not trigger a render");
}
}
}
@@ -805,6 +859,7 @@ class DashboardController {
}
private buildSyntheticRingInput(kind: "click" | "double-click" | "scroll-up" | "scroll-down"): RawInputEvent {
const frameId = frameTimings.startFrame(`input:synthetic:${kind}`);
switch (kind) {
case "click":
return {
@@ -813,6 +868,7 @@ class DashboardController {
eventType: OsEventTypeList.CLICK_EVENT,
eventSource: EventSourceType.TOUCH_EVENT_FROM_RING,
systemExitReasonCode: 0,
frameId,
};
case "double-click":
return {
@@ -821,6 +877,7 @@ class DashboardController {
eventType: OsEventTypeList.DOUBLE_CLICK_EVENT,
eventSource: EventSourceType.TOUCH_EVENT_FROM_RING,
systemExitReasonCode: 0,
frameId,
};
case "scroll-up":
return {
@@ -829,6 +886,7 @@ class DashboardController {
eventType: OsEventTypeList.SCROLL_TOP_EVENT,
eventSource: EventSourceType.TOUCH_EVENT_FROM_RING,
systemExitReasonCode: 0,
frameId,
};
case "scroll-down":
default:
@@ -838,6 +896,7 @@ class DashboardController {
eventType: OsEventTypeList.SCROLL_BOTTOM_EVENT,
eventSource: EventSourceType.TOUCH_EVENT_FROM_RING,
systemExitReasonCode: 0,
frameId,
};
}
}
+74 -2
View File
@@ -1,4 +1,5 @@
import { Utils } from "@nativescript/core";
import * as frameTimings from "./frame-timings";
declare const com: any;
@@ -32,6 +33,7 @@ export type RawInputEvent =
eventType: number;
eventSource: number;
systemExitReasonCode: number;
frameId: number;
}
| {
kind: "text-click";
@@ -39,6 +41,7 @@ export type RawInputEvent =
eventType: number;
eventSource: number;
systemExitReasonCode: number;
frameId: number;
}
| {
kind: "sys-event";
@@ -46,6 +49,7 @@ export type RawInputEvent =
eventType: number;
eventSource: number;
systemExitReasonCode: number;
frameId: number;
};
function toJavaByteArray(bytes: Uint8Array): number[] {
@@ -67,6 +71,10 @@ export class FaceclawCommunicatorBridge {
private readonly listenerProxy: any;
private javaCallQueue: Promise<void> = Promise.resolve();
private readonly frameMetricWaiters = new Set<(metrics: FrameMetrics) => void>();
// Recent frame-finished outcomes from the Java side, so waitForFrameFinished
// does not race against finishes that land before the wait starts.
private readonly finishedFrameOutcomes = new Map<number, string>();
private readonly frameFinishedWaiters = new Map<number, Set<(outcome: string) => void>>();
private readonly logListeners = new Set<(line: string) => void>();
private readonly stateListeners = new Set<(state: CommunicatorState) => void>();
private readonly ringListeners = new Set<(event: RawInputEvent) => void>();
@@ -101,6 +109,7 @@ export class FaceclawCommunicatorBridge {
eventType: number,
eventSource: number,
systemExitReasonCode: number,
frameId: number,
) => {
const event = {
kind: String(kind) as RawInputEvent["kind"],
@@ -108,7 +117,9 @@ export class FaceclawCommunicatorBridge {
eventType: Number(eventType),
eventSource: Number(eventSource),
systemExitReasonCode: Number(systemExitReasonCode),
frameId: Number(frameId),
};
frameTimings.logFrame(event.frameId, "input event received on JS side");
this.emitAsync(this.ringListeners, event);
},
onBatteryState: (headsetBattery: number, headsetCharging: number) => {
@@ -134,6 +145,9 @@ export class FaceclawCommunicatorBridge {
}
this.emitAsync(this.frameMetricsListeners, metrics);
},
onFrameFinished: (frameId: number, outcome: string) => {
this.recordFrameFinished(Number(frameId), String(outcome));
},
});
this.communicator.setListener(this.listenerProxy);
}
@@ -201,6 +215,62 @@ export class FaceclawCommunicatorBridge {
return this.communicator;
}
private recordFrameFinished(frameId: number, outcome: string): void {
if (!Number.isFinite(frameId) || frameId <= 0) return;
this.finishedFrameOutcomes.set(frameId, outcome);
while (this.finishedFrameOutcomes.size > 128) {
const oldest = this.finishedFrameOutcomes.keys().next().value;
if (oldest === undefined) break;
this.finishedFrameOutcomes.delete(oldest);
}
const waiters = this.frameFinishedWaiters.get(frameId);
if (waiters) {
this.frameFinishedWaiters.delete(frameId);
for (const waiter of waiters) {
setTimeout(() => waiter(outcome), 0);
}
}
}
/**
* Resolve with the frame's outcome once the Java side finishes it (sent,
* discarded, or timed out), or with null after timeoutMs. Used as transmit
* backpressure: unlike waiting for frame metrics, this also resolves when a
* frame is discarded (e.g. deduped as unchanged), so no-op renders do not
* stall the render loop.
*/
waitForFrameFinished(frameId: number, timeoutMs: number): Promise<string | null> {
const known = this.finishedFrameOutcomes.get(frameId);
if (known !== undefined) return Promise.resolve(known);
if (frameId <= 0) return Promise.resolve(null);
const delayMs = Math.max(1, Math.round(nonNegativeNumber(timeoutMs)));
return new Promise((resolve) => {
let settled = false;
const onFinished = (outcome: string) => {
if (settled) return;
settled = true;
clearTimeout(timeoutHandle);
resolve(outcome);
};
let waiters = this.frameFinishedWaiters.get(frameId);
if (!waiters) {
waiters = new Set();
this.frameFinishedWaiters.set(frameId, waiters);
}
waiters.add(onFinished);
const timeoutHandle = setTimeout(() => {
if (settled) return;
settled = true;
const pending = this.frameFinishedWaiters.get(frameId);
if (pending) {
pending.delete(onFinished);
if (pending.size === 0) this.frameFinishedWaiters.delete(frameId);
}
resolve(null);
}, delayMs);
});
}
waitForNextFrameMetrics(timeoutMs: number): Promise<FrameMetrics | null> {
const delayMs = Math.max(1, Math.round(nonNegativeNumber(timeoutMs)));
return new Promise((resolve) => {
@@ -229,15 +299,17 @@ export class FaceclawCommunicatorBridge {
await this.enqueueJavaCall(() => this.communicator.setG2ScreenOn(Boolean(screenOn)));
}
async submitDashboardImage(image8bpp: Uint8Array, width: number, height: number, fingerprint: string, paintMs = -1): Promise<void> {
async submitDashboardImage(image8bpp: Uint8Array, width: number, height: number, fingerprint: string, paintMs = -1, frameId = 0): Promise<void> {
const snapshot = new Uint8Array(image8bpp);
await this.enqueueJavaCall(() => {
const javaBytes = frameTimings.span(frameId, "js-to-java-copy", () => toJavaByteArray(snapshot));
this.communicator.submitDashboardImage(
toJavaByteArray(snapshot),
javaBytes,
Math.round(width),
Math.round(height),
fingerprint,
Math.round(nonNegativeNumber(paintMs)),
Math.round(nonNegativeNumber(frameId)),
);
});
}
+92
View File
@@ -0,0 +1,92 @@
/**
* TS-side wrapper for the Java FrameTimings singleton (per-frame latency
* instrumentation; see FrameTimings.java). Frame ID 0 means "no frame" and is
* ignored by every method, so callers never need to null-check.
*
* Because the JS side is single-threaded, this module also tracks a "current
* frame" so that leaf drawing/IO code can record spans without threading a
* frame ID through every call signature.
*/
declare const com: any;
declare const global: any;
let javaInstance: any = null;
let javaUnavailable = false;
// Fallback IDs when the Java class is unavailable (e.g. unit tests): negative
// so they can never collide with real Java-issued frame IDs.
let fallbackNextFrameId = -1;
let currentFrameId = 0;
function getJava(): any {
if (javaInstance === null && !javaUnavailable) {
try {
if (typeof com !== "undefined" && global.isAndroid) {
javaInstance = com.faceclaw.app.FrameTimings.getInstance();
} else {
javaUnavailable = true;
}
} catch {
javaUnavailable = true;
}
}
return javaInstance;
}
export function startFrame(reason: string): number {
const java = getJava();
if (!java) return fallbackNextFrameId--;
return Number(java.startFrame(reason));
}
export function logFrame(frameId: number, message: string): void {
if (frameId <= 0) return;
getJava()?.log(frameId, message);
}
export function spanStart(frameId: number, name: string): void {
if (frameId <= 0) return;
getJava()?.spanStart(frameId, name);
}
export function spanEnd(frameId: number, name: string): void {
if (frameId <= 0) return;
getJava()?.spanEnd(frameId, name);
}
export function finishFrame(frameId: number, outcome: string): void {
if (frameId <= 0) return;
getJava()?.finishFrame(frameId, outcome);
}
export function span<T>(frameId: number, name: string, fn: () => T): T {
spanStart(frameId, name);
try {
return fn();
} finally {
spanEnd(frameId, name);
}
}
/** Set the current frame while running fn, for leaf code using the *Current helpers. */
export function runWithFrame<T>(frameId: number, fn: () => T): T {
const previous = currentFrameId;
currentFrameId = frameId;
try {
return fn();
} finally {
currentFrameId = previous;
}
}
export function currentFrame(): number {
return currentFrameId;
}
export function logCurrent(message: string): void {
logFrame(currentFrameId, message);
}
export function spanCurrent<T>(name: string, fn: () => T): T {
return span(currentFrameId, name, fn);
}
+13 -7
View File
@@ -1,4 +1,5 @@
import { GrayImage } from "../graphics/image";
import { logCurrent, spanCurrent } from "./frame-timings";
import { toUint8Array } from "../util/array-util";
declare const com: any;
@@ -39,13 +40,16 @@ export function readActiveNotificationIcons(maxIcons: number): GrayImage[] {
const now = Date.now();
if (now - cachedAtMs < ICON_CACHE_MS) {
logCurrent("notification icons served from cache");
return cachedIcons.map(icon => icon.clone());
}
const bytes = toUint8Array(
com.faceclaw.app.FaceclawMediaNotificationListenerService.getActiveNotificationIconGrays(
ICON_SIZE,
maxIcons,
const bytes = spanCurrent("fetch-notification-icons", () =>
toUint8Array(
com.faceclaw.app.FaceclawMediaNotificationListenerService.getActiveNotificationIconGrays(
ICON_SIZE,
maxIcons,
),
),
);
const iconByteLength = ICON_SIZE * ICON_SIZE;
@@ -65,9 +69,11 @@ export function readActiveNotificationIcons(maxIcons: number): GrayImage[] {
export function readActiveNotifications(maxNotifications = 50): AndroidNotification[] {
if (!global.isAndroid || maxNotifications <= 0) return [];
try {
const json = String(
com.faceclaw.app.FaceclawMediaNotificationListenerService.getActiveNotificationsJson(
Math.max(0, Math.round(maxNotifications)),
const json = spanCurrent("fetch-notifications-json", () =>
String(
com.faceclaw.app.FaceclawMediaNotificationListenerService.getActiveNotificationsJson(
Math.max(0, Math.round(maxNotifications)),
),
),
);
const parsed = JSON.parse(json);
+5 -2
View File
@@ -1,5 +1,6 @@
import { Utils } from "@nativescript/core";
import { GrayImage } from "../graphics/image";
import { spanCurrent } from "./frame-timings";
import { toUint8Array } from "~/util/array-util";
declare const com: any;
@@ -21,8 +22,10 @@ export function readSystemStatusIcons(): GrayImage[] {
const context = Utils.android.getApplicationContext();
if (!context) return [];
const bytes = toUint8Array(
com.faceclaw.app.FaceclawSystemStatusIconProvider.getSystemStatusIconGrays(context, ICON_SIZE),
const bytes = spanCurrent("fetch-system-status-icons", () =>
toUint8Array(
com.faceclaw.app.FaceclawSystemStatusIconProvider.getSystemStatusIconGrays(context, ICON_SIZE),
),
);
const iconByteLength = ICON_SIZE * ICON_SIZE;
const iconCount = Math.floor(bytes.length / iconByteLength);
+3
View File
@@ -1,4 +1,5 @@
import { GrayImage } from "../../graphics/image";
import { spanCurrent } from "../../native/frame-timings";
import { BATTERY_ICON_WIDTH, drawBattery } from "../../graphics/battery";
import { readActiveNotificationIcons } from "../../native/notification-icons";
import { readPhoneBatteryState } from "../../native/phone-battery";
@@ -149,6 +150,7 @@ function pad2(value: number): string {
}
export function drawSystemCard(image: GrayImage, bounds: DashboardPluginCardBounds): void {
spanCurrent("draw-system-card", () => {
const now = new Date();
const logo = getDashboardLogo();
@@ -159,5 +161,6 @@ export function drawSystemCard(image: GrayImage, bounds: DashboardPluginCardBoun
image.drawText(mediumFont, infoX, bounds.y + 10, systemCardNameSetting.get(), 200);
image.drawText(mediumFont, infoX, bounds.y + 32, formatDashboardDate(now), 200);
drawSystemCardFlowItems(image, bounds);
});
}
+15 -12
View File
@@ -1,5 +1,6 @@
import { G2_LENS_HEIGHT, G2_LENS_WIDTH, GrayImage } from "../graphics/image";
import { BdfFont } from "../graphics/bdffont";
import { spanCurrent } from "../native/frame-timings";
import { type ConfigSettingString } from "./dashboard-settings";
export type DashboardInputEvent =
@@ -79,18 +80,20 @@ export class LayerStack {
private paintLayer(index: number): GrayImage {
const layer = this.layers[index]!;
let cachedBelow: GrayImage | null = null;
return layer.paint(this.ctx, () => {
if (cachedBelow) {
return spanCurrent(`paint[${index}]:${layer.constructor.name}`, () =>
layer.paint(this.ctx, () => {
if (cachedBelow) {
return cachedBelow;
}
if (index <= 0) {
cachedBelow = new GrayImage(G2_LENS_WIDTH, G2_LENS_HEIGHT, 0);
} else if (layer.paintOverBase) {
cachedBelow = this.paintLayer(0);
} else {
cachedBelow = this.paintLayer(index - 1);
}
return cachedBelow;
}
if (index <= 0) {
cachedBelow = new GrayImage(G2_LENS_WIDTH, G2_LENS_HEIGHT, 0);
} else if (layer.paintOverBase) {
cachedBelow = this.paintLayer(0);
} else {
cachedBelow = this.paintLayer(index - 1);
}
return cachedBelow;
});
}),
);
}
}