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

@@ -101,6 +101,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
private String desiredFingerprint = "";
private byte[] desiredBmp = new byte[0];
private int desiredPaintMs;
private int desiredFrameId;
private final ArrayDeque<OutboundMessage> pendingMessages = new ArrayDeque<>();
private final ArrayDeque<OutboundMessage> inFlightMessages = new ArrayDeque<>();
@@ -109,6 +110,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
public FaceclawBleCommunicator(Context context, String rightAddress, String leftAddress, String ringAddress) {
this.appContext = context.getApplicationContext();
FrameTimings.getInstance().init(appContext);
this.powerManager = (PowerManager) appContext.getSystemService(Context.POWER_SERVICE);
this.bleManager = new FaceclawBleManager(appContext);
this.bleManager.setListener(this);
@@ -229,17 +231,27 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
int width,
int height,
String fingerprint,
int paintMs
int paintMs,
int frameId
) {
Log.i(TAG, "Received an updated frame ");
// Convert the full-screen 8bpp grayscale buffer into the BMP wire format here so
// that all framing concerns live on the Java side.
FrameTimings.getInstance().spanStart(frameId, "bmp-convert");
byte[] bmp = image8bpp == null ? new byte[0] : BmpUtil.build4bppBmp(image8bpp, width, height);
FrameTimings.getInstance().spanEnd(frameId, "bmp-convert");
int supersededFrameId;
synchronized (desiredTilesLock) {
supersededFrameId = desiredFrameId;
desiredBmp = bmp;
desiredFingerprint = fingerprint == null ? "" : fingerprint;
desiredPaintMs = paintMs;
desiredFrameId = frameId;
}
if (supersededFrameId != 0 && supersededFrameId != frameId) {
finishFrame(supersededFrameId, "discarded: superseded by frame#" + frameId + " before send");
}
FrameTimings.getInstance().log(frameId, "image submitted as desired frame");
interruptibleSleep.interrupt();
}
@@ -452,7 +464,10 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
interruptibleSleep.interrupt();
if (event != null) {
emitRingEvent(event.kind, event.containerName, event.eventType, event.eventSource, event.systemExitReasonCode);
int frameId = FrameTimings.getInstance().startFrame(
"input:" + event.kind + " type=" + event.eventType + " src=" + event.eventSource);
FrameTimings.getInstance().log(frameId, "input event decoded from BLE notification");
emitRingEvent(event.kind, event.containerName, event.eventType, event.eventSource, event.systemExitReasonCode, frameId);
}
}
@@ -470,7 +485,9 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
lastConnectionOrInputAtMs = arrivalMs;
}
logLine("direct ring " + decoded.label + " " + decoded.detail + " raw=" + hex(data));
emitRingEvent(event.kind, event.containerName, event.eventType, event.eventSource, event.systemExitReasonCode);
int frameId = FrameTimings.getInstance().startFrame("input:ring:" + decoded.label);
FrameTimings.getInstance().log(frameId, "input event decoded from direct ring notification");
emitRingEvent(event.kind, event.containerName, event.eventType, event.eventSource, event.systemExitReasonCode, frameId);
interruptibleSleep.interrupt();
}
@@ -729,6 +746,8 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
OutboundMessage messageToPrewrite = null;
long now = SystemClock.elapsedRealtime();
maybeFinishNoChangeDesiredFrame();
synchronized (lock) {
if (!inFlightMessages.isEmpty()) {
OutboundMessage oldest = inFlightMessages.peekFirst();
@@ -808,6 +827,26 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
}
/**
* If the desired image already matches what the glasses display, nothing will
* ever be enqueued for it, so finish its frame now (otherwise the TS side
* would block on it until its backpressure timeout).
*/
private void maybeFinishNoChangeDesiredFrame() {
int frameIdToFinish = 0;
synchronized (lock) {
synchronized (desiredTilesLock) {
if (desiredFrameId != 0 && !displayedFingerprint.isEmpty() && desiredFingerprint.equals(displayedFingerprint)) {
frameIdToFinish = desiredFrameId;
desiredFrameId = 0;
}
}
}
if (frameIdToFinish != 0) {
finishFrame(frameIdToFinish, "discarded: no change from displayed image");
}
}
private boolean shouldBlockPrewriteForHeartbeatLocked(long now) {
if (shutdownRequested || !warmedUp || !fixedLayoutCreated) {
return false;
@@ -1041,14 +1080,18 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
if (message.imageUpdateId <= 0) {
return;
}
BleImageOptimizer.ImageUpdateStats stats = imageUpdateStats.get(message.imageUpdateId);
int frameId = stats == null ? 0 : stats.frameId;
if (message.imageMessageNumber == 1) {
BleImageOptimizer.ImageUpdateStats stats = imageUpdateStats.get(message.imageUpdateId);
if (stats != null && stats.firstWriteStartedAtMs <= 0) {
stats.firstWriteStartedAtMs = message.writeStartedAtMs > 0 ? message.writeStartedAtMs : message.sentAtMs;
}
FrameTimings.getInstance().log(frameId, "first bluetooth packet sent");
logImageUpdateLandmarkLocked("first bluetooth message sent", message, message.sentAtMs);
}
if (message.imageMessageNumber == message.imageMessageCount) {
FrameTimings.getInstance().log(frameId,
"last bluetooth packet sent (message " + message.imageMessageNumber + "/" + message.imageMessageCount + ")");
logImageUpdateLandmarkLocked("last bluetooth message sent", message, message.sentAtMs);
}
}
@@ -1062,9 +1105,23 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
if (stats != null && stats.firstWriteStartedAtMs > 0) {
emitFrameMetrics(stats.paintMs, (int) Math.max(0, ackedAtMs - stats.firstWriteStartedAtMs), stats.tileCount);
}
if (stats != null) {
finishFrame(stats.frameId, "sent");
}
logImageUpdateLandmarkLocked("last bluetooth message acked", message, ackedAtMs);
}
/** Remove the stats entry for an image update that will not complete, finishing its frame. */
private void discardImageUpdateStatsLocked(int imageUpdateId, String reason) {
if (imageUpdateId <= 0) {
return;
}
BleImageOptimizer.ImageUpdateStats stats = imageUpdateStats.remove(imageUpdateId);
if (stats != null) {
finishFrame(stats.frameId, "discarded: " + reason);
}
}
private void logImageUpdateLandmarkLocked(String event, OutboundMessage message, long elapsedMs) {
logLine("image update#" + message.imageUpdateId + " " + event
+ " at " + timestamp(elapsedMs)
@@ -1155,30 +1212,38 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
String fingerprint = getDesiredFingerprint();
byte[] bmp;
int paintMs;
int frameId;
synchronized (desiredTilesLock) {
bmp = desiredBmp;
paintMs = desiredPaintMs;
frameId = desiredFrameId;
desiredFrameId = 0;
}
if (bmp == null) {
bmp = new byte[0];
}
if (Arrays.equals(bmp, displayedBmp)) {
displayedFingerprint = fingerprint;
finishFrame(frameId, "discarded: image content identical to displayed");
return;
}
FrameTimings.getInstance().spanStart(frameId, "compress-and-plan");
BleImageOptimizer.TileImagePlan plan =
new BleImageOptimizer.TileImagePlan(0, DASHBOARD_TILE, bmp, nextMapSessionId());
plan.fragments = BleImageOptimizer.planImageFragments(plan.payload, ConnectionOptions.IMAGE_FRAGMENT_SIZE);
FrameTimings.getInstance().spanEnd(frameId, "compress-and-plan");
int updateId = nextImageUpdateId++;
int messageCount = plan.fragments.size();
imageUpdateStats.put(updateId, new BleImageOptimizer.ImageUpdateStats(paintMs, 1));
imageUpdateStats.put(updateId, new BleImageOptimizer.ImageUpdateStats(paintMs, 1, frameId));
for (int i = 0; i < plan.fragments.size(); i++) {
BleProtocol.ImageFragment fragment = plan.fragments.get(i);
enqueueImageFragmentLocked(plan, fragment, fingerprint, updateId, i + 1, messageCount, true);
}
FrameTimings.getInstance().log(frameId, "queued image update#" + updateId
+ " messages=" + messageCount + " payload=" + plan.payload.length + "B");
logLine("queue image update#" + updateId + " fingerprint=" + fingerprint
+ " messages=" + messageCount);
}
@@ -1221,7 +1286,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
}
};
message.onTimeout = () -> {
imageUpdateStats.remove(message.imageUpdateId);
discardImageUpdateStatsLocked(message.imageUpdateId, "image ack timeout (will retry)");
clearMessagesOfKindLocked("image");
displayedFingerprint = "";
displayedBmp = new byte[0];
@@ -1325,7 +1390,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
pendingIterator.remove();
discardPrewriteIfMatchesLocked(message);
if ("image".equals(kind)) {
imageUpdateStats.remove(message.imageUpdateId);
discardImageUpdateStatsLocked(message.imageUpdateId, "pending messages cleared (" + kind + ")");
}
magicPool.release(message.sid, message.magic, message.label, "cleared pending " + kind);
}
@@ -1336,7 +1401,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
if (kind.equals(message.kind)) {
inFlightIterator.remove();
if ("image".equals(kind)) {
imageUpdateStats.remove(message.imageUpdateId);
discardImageUpdateStatsLocked(message.imageUpdateId, "inflight messages cleared (" + kind + ")");
}
magicPool.release(message.sid, message.magic, message.label, "cleared inflight " + kind);
}
@@ -1352,6 +1417,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
while (!pendingMessages.isEmpty()) {
var message = pendingMessages.removeFirst();
discardPrewriteIfMatchesLocked(message);
discardImageUpdateStatsLocked(message.imageUpdateId, "pending messages cleared: " + reason);
magicPool.release(message.sid, message.magic, message.label, "cleared pending: " + reason);
}
}
@@ -1359,6 +1425,7 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
private void clearInFlightMessagesLocked(String reason) {
while (!inFlightMessages.isEmpty()) {
var message = inFlightMessages.removeFirst();
discardImageUpdateStatsLocked(message.imageUpdateId, "inflight messages cleared: " + reason);
magicPool.release(message.sid, message.magic, message.label, "cleared inflight: " + reason);
}
}
@@ -1457,17 +1524,39 @@ public class FaceclawBleCommunicator implements FaceclawBleListener, Runnable {
return false;
}
private void emitRingEvent(String kind, String containerName, int eventType, int eventSource, int systemExitReasonCode) {
private void emitRingEvent(String kind, String containerName, int eventType, int eventSource, int systemExitReasonCode, int frameId) {
final FaceclawBleCommunicatorListener current = listener;
if (current == null) {
FrameTimings.getInstance().finishFrame(frameId, "discarded: no listener attached");
return;
}
final String containerNameSnapshot = containerName == null ? "" : containerName;
mainHandler.post(() -> {
FrameTimings.getInstance().log(frameId, "dispatching input event on main thread");
try {
current.onRingEvent(kind, containerNameSnapshot, eventType, eventSource, systemExitReasonCode);
current.onRingEvent(kind, containerNameSnapshot, eventType, eventSource, systemExitReasonCode, frameId);
} catch (Throwable t) {
Log.w(TAG, "listener onRingEvent failed", t);
FrameTimings.getInstance().finishFrame(frameId, "discarded: listener onRingEvent failed");
}
});
}
/** Finish a frame owned by the communicator and tell the TS side, which may be awaiting it. */
private void finishFrame(int frameId, String outcome) {
if (frameId <= 0) {
return;
}
FrameTimings.getInstance().finishFrame(frameId, outcome);
final FaceclawBleCommunicatorListener current = listener;
if (current == null) {
return;
}
mainHandler.post(() -> {
try {
current.onFrameFinished(frameId, outcome);
} catch (Throwable t) {
Log.w(TAG, "listener onFrameFinished failed", t);
}
});
}
@@ -3,8 +3,9 @@ package com.faceclaw.app;
public interface FaceclawBleCommunicatorListener {
void onLog(String line);
void onStateChange(String phase, String status);
void onRingEvent(String kind, String containerName, int eventType, int eventSource, int systemExitReasonCode);
void onRingEvent(String kind, String containerName, int eventType, int eventSource, int systemExitReasonCode, int frameId);
void onBatteryState(int headsetBattery, int headsetCharging);
void onEvenAppConflict(String message);
void onFrameMetrics(int paintMs, int transmitMs, int tileCount);
void onFrameFinished(int frameId, String outcome);
}
@@ -0,0 +1,384 @@
package com.faceclaw.app;
import android.content.Context;
import android.os.SystemClock;
import android.util.Log;
import java.io.File;
import java.io.FileOutputStream;
import java.io.OutputStreamWriter;
import java.io.Writer;
import java.nio.charset.StandardCharsets;
import java.text.SimpleDateFormat;
import java.util.ArrayDeque;
import java.util.ArrayList;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.Iterator;
import java.util.List;
import java.util.Locale;
import java.util.Map;
/**
* Per-frame timing instrumentation, shared between the Java BLE layer and the
* Typescript UI layer. A "frame" starts when we receive an input event (or a
* timer fires and we decide to redraw), and finishes when the resulting screen
* update has been fully transmitted to the glasses, is discarded unsent, or
* times out because nobody reported finishing it.
*
* All public methods are thread-safe and cheap enough to call from the BLE
* worker thread, the Android main thread, and the JS thread. Frame IDs are
* positive ints; 0 means "no frame" and is silently ignored everywhere, so
* callers do not need to null-check.
*
* Statistics (p50/p90/p99 of event-to-last-ack for sent frames) and full log
* lines for recent and slowest frames are periodically exported to
* getExternalFilesDir()/frame-timings.txt, retrievable via
* adb pull /sdcard/Android/data/<pkg>/files/frame-timings.txt
*/
public final class FrameTimings {
private static final String TAG = "FrameTimings";
private static final FrameTimings INSTANCE = new FrameTimings();
/** Frames still open after this long are finished as "timeout". */
private static final long FRAME_TIMEOUT_MS = 30_000;
private static final long EXPORT_INTERVAL_MS = 15_000;
private static final long SWEEP_INTERVAL_MS = 5_000;
private static final int RECENT_FRAMES_KEPT = 50;
private static final int SLOWEST_FRAMES_KEPT = 20;
private static final int SENT_DURATIONS_WINDOW = 512;
private static final int MAX_LINES_PER_FRAME = 200;
private static final String EXPORT_FILE_NAME = "frame-timings.txt";
public static FrameTimings getInstance() {
return INSTANCE;
}
private static final class Frame {
final int id;
final String reason;
final long startedAtMs; // SystemClock.elapsedRealtime()
final long startedWallClockMs;
final List<String> lines = new ArrayList<>();
final Map<String, Long> openSpans = new HashMap<>();
long finishedAtMs;
String outcome; // null while open; "sent", "discarded: ...", "timeout: ..."
Frame(int id, String reason, long startedAtMs, long startedWallClockMs) {
this.id = id;
this.reason = reason;
this.startedAtMs = startedAtMs;
this.startedWallClockMs = startedWallClockMs;
}
long durationMs() {
return finishedAtMs - startedAtMs;
}
boolean wasSent() {
return outcome != null && outcome.startsWith("sent");
}
}
private final Object lock = new Object();
private final Map<Integer, Frame> activeFrames = new HashMap<>();
private final ArrayDeque<Frame> recentFrames = new ArrayDeque<>();
private final List<Frame> slowestSentFrames = new ArrayList<>();
private final ArrayDeque<Long> sentDurations = new ArrayDeque<>();
private int nextFrameId = 1;
private long framesStarted;
private long framesSent;
private long framesDiscarded;
private long framesTimedOut;
private boolean exportDirty;
private File exportDir;
private Thread exportThread;
private FrameTimings() {
}
/** Idempotent; enables filesystem export. Safe to call from any constructor path. */
public void init(Context context) {
File dir = context.getApplicationContext().getExternalFilesDir(null);
if (dir == null) {
dir = context.getApplicationContext().getFilesDir();
}
synchronized (lock) {
exportDir = dir;
if (exportThread == null) {
exportThread = new Thread(this::exportLoop, "FrameTimingsExport");
exportThread.setDaemon(true);
exportThread.start();
}
}
}
/** Begin a frame; reason is a short label like "input:sys-event:0". Returns the frame ID. */
public int startFrame(String reason) {
long now = SystemClock.elapsedRealtime();
Frame frame;
synchronized (lock) {
frame = new Frame(nextFrameId++, reason == null ? "" : reason, now, System.currentTimeMillis());
activeFrames.put(frame.id, frame);
framesStarted++;
}
return frame.id;
}
public void log(int frameId, String message) {
long now = SystemClock.elapsedRealtime();
synchronized (lock) {
Frame frame = activeFrames.get(frameId);
if (frame == null) {
return;
}
addLineLocked(frame, now, message);
}
}
public void spanStart(int frameId, String name) {
long now = SystemClock.elapsedRealtime();
synchronized (lock) {
Frame frame = activeFrames.get(frameId);
if (frame == null) {
return;
}
frame.openSpans.put(name, now);
addLineLocked(frame, now, "span " + name + " start");
}
}
public void spanEnd(int frameId, String name) {
long now = SystemClock.elapsedRealtime();
synchronized (lock) {
Frame frame = activeFrames.get(frameId);
if (frame == null) {
return;
}
Long startedAt = frame.openSpans.remove(name);
if (startedAt == null) {
addLineLocked(frame, now, "span " + name + " end (start not recorded)");
} else {
addLineLocked(frame, now, "span " + name + " end (" + (now - startedAt) + "ms)");
}
}
}
/**
* Finish a frame. Outcomes: "sent" (counted in latency percentiles), anything
* starting with "discarded", or "timeout". First finish wins; later calls for
* the same frame are ignored, so racing completion paths are safe.
*/
public void finishFrame(int frameId, String outcome) {
long now = SystemClock.elapsedRealtime();
Frame finished;
synchronized (lock) {
Frame frame = activeFrames.remove(frameId);
if (frame == null) {
return;
}
finishFrameLocked(frame, now, outcome == null ? "discarded: no outcome given" : outcome);
finished = frame;
}
Log.i(TAG, "frame#" + finished.id + " [" + finished.reason + "] -> " + finished.outcome
+ " in " + finished.durationMs() + "ms");
}
/** One-line stats summary, e.g. for showing in the phone UI. */
public String statsSummary() {
synchronized (lock) {
long[] percentiles = sentPercentilesLocked();
return "frames started=" + framesStarted + " sent=" + framesSent
+ " discarded=" + framesDiscarded + " timeout=" + framesTimedOut
+ (percentiles == null
? ""
: " | sent-latency p50=" + percentiles[0] + "ms p90=" + percentiles[1]
+ "ms p99=" + percentiles[2] + "ms max=" + percentiles[3] + "ms");
}
}
// ---------------------------------------------------------------------
private void addLineLocked(Frame frame, long now, String message) {
if (frame.lines.size() >= MAX_LINES_PER_FRAME) {
if (frame.lines.size() == MAX_LINES_PER_FRAME) {
frame.lines.add("... line cap reached");
}
return;
}
frame.lines.add(String.format(Locale.US, "%+6dms [%s] %s",
now - frame.startedAtMs, Thread.currentThread().getName(), message));
}
private void finishFrameLocked(Frame frame, long now, String outcome) {
frame.finishedAtMs = now;
frame.outcome = outcome;
for (Map.Entry<String, Long> open : frame.openSpans.entrySet()) {
frame.lines.add(String.format(Locale.US, "%+6dms span %s never ended (started at +%dms)",
now - frame.startedAtMs, open.getKey(), open.getValue() - frame.startedAtMs));
}
frame.openSpans.clear();
addLineLocked(frame, now, "finished: " + outcome);
if (frame.wasSent()) {
framesSent++;
sentDurations.addLast(frame.durationMs());
while (sentDurations.size() > SENT_DURATIONS_WINDOW) {
sentDurations.removeFirst();
}
insertSlowestLocked(frame);
} else if (outcome.startsWith("timeout")) {
framesTimedOut++;
} else {
framesDiscarded++;
}
recentFrames.addLast(frame);
while (recentFrames.size() > RECENT_FRAMES_KEPT) {
recentFrames.removeFirst();
}
exportDirty = true;
}
private void insertSlowestLocked(Frame frame) {
slowestSentFrames.add(frame);
Collections.sort(slowestSentFrames, (a, b) -> Long.compare(b.durationMs(), a.durationMs()));
while (slowestSentFrames.size() > SLOWEST_FRAMES_KEPT) {
slowestSentFrames.remove(slowestSentFrames.size() - 1);
}
}
/** {p50, p90, p99, max} over the rolling sent-duration window, or null if empty. */
private long[] sentPercentilesLocked() {
if (sentDurations.isEmpty()) {
return null;
}
List<Long> sorted = new ArrayList<>(sentDurations);
Collections.sort(sorted);
return new long[] {
percentileOfSorted(sorted, 50),
percentileOfSorted(sorted, 90),
percentileOfSorted(sorted, 99),
sorted.get(sorted.size() - 1),
};
}
private static long percentileOfSorted(List<Long> sorted, int percentile) {
int index = (int) Math.ceil(percentile / 100.0 * sorted.size()) - 1;
return sorted.get(Math.max(0, Math.min(sorted.size() - 1, index)));
}
private void sweepTimedOutFrames() {
long now = SystemClock.elapsedRealtime();
List<Frame> timedOut = new ArrayList<>();
synchronized (lock) {
Iterator<Map.Entry<Integer, Frame>> iterator = activeFrames.entrySet().iterator();
while (iterator.hasNext()) {
Frame frame = iterator.next().getValue();
if (now - frame.startedAtMs >= FRAME_TIMEOUT_MS) {
iterator.remove();
finishFrameLocked(frame, now, "timeout: never reported finished");
timedOut.add(frame);
}
}
}
for (Frame frame : timedOut) {
Log.w(TAG, "frame#" + frame.id + " [" + frame.reason + "] timed out after "
+ frame.durationMs() + "ms without being finished");
}
}
private void exportLoop() {
long lastExportAtMs = 0;
while (true) {
try {
Thread.sleep(SWEEP_INTERVAL_MS);
} catch (InterruptedException e) {
return;
}
try {
sweepTimedOutFrames();
long now = SystemClock.elapsedRealtime();
boolean shouldExport;
synchronized (lock) {
shouldExport = exportDirty && exportDir != null && now - lastExportAtMs >= EXPORT_INTERVAL_MS;
}
if (shouldExport) {
lastExportAtMs = now;
exportToFile();
}
} catch (Throwable t) {
Log.w(TAG, "export loop error", t);
}
}
}
private void exportToFile() {
String content;
File dir;
synchronized (lock) {
dir = exportDir;
if (dir == null) {
return;
}
content = buildExportLocked();
exportDirty = false;
}
File target = new File(dir, EXPORT_FILE_NAME);
File temp = new File(dir, EXPORT_FILE_NAME + ".tmp");
try {
try (Writer writer = new OutputStreamWriter(new FileOutputStream(temp), StandardCharsets.UTF_8)) {
writer.write(content);
}
if (!temp.renameTo(target)) {
Log.w(TAG, "failed to rename " + temp + " to " + target);
}
} catch (Throwable t) {
Log.w(TAG, "failed to export frame timings", t);
}
}
private String buildExportLocked() {
SimpleDateFormat wallClockFormat = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS", Locale.US);
StringBuilder out = new StringBuilder(64 * 1024);
out.append("FrameTimings export at ").append(wallClockFormat.format(new Date())).append('\n');
out.append(statsSummaryLocked()).append('\n');
out.append('\n');
out.append("=== slowest sent frames ===\n");
for (Frame frame : slowestSentFrames) {
appendFrameLocked(out, frame, wallClockFormat);
}
out.append("=== recent frames (oldest first) ===\n");
for (Frame frame : recentFrames) {
appendFrameLocked(out, frame, wallClockFormat);
}
return out.toString();
}
private String statsSummaryLocked() {
long[] percentiles = sentPercentilesLocked();
return "frames started=" + framesStarted + " sent=" + framesSent
+ " discarded=" + framesDiscarded + " timeout=" + framesTimedOut
+ " open=" + activeFrames.size()
+ (percentiles == null
? ""
: "\nsent-frame latency (last " + sentDurations.size() + "): p50=" + percentiles[0]
+ "ms p90=" + percentiles[1] + "ms p99=" + percentiles[2]
+ "ms max=" + percentiles[3] + "ms");
}
private void appendFrameLocked(StringBuilder out, Frame frame, SimpleDateFormat wallClockFormat) {
out.append("frame#").append(frame.id)
.append(" [").append(frame.reason).append(']')
.append(" started ").append(wallClockFormat.format(new Date(frame.startedWallClockMs)))
.append(" duration ").append(frame.durationMs()).append("ms")
.append(" outcome ").append(frame.outcome)
.append('\n');
for (String line : frame.lines) {
out.append(" ").append(line).append('\n');
}
}
}
@@ -129,11 +129,13 @@ public final class BleImageOptimizer {
public static final class ImageUpdateStats {
final int paintMs;
final int tileCount;
final int frameId;
long firstWriteStartedAtMs;
ImageUpdateStats(int paintMs, int tileCount) {
ImageUpdateStats(int paintMs, int tileCount, int frameId) {
this.paintMs = Math.max(0, paintMs);
this.tileCount = tileCount;
this.frameId = frameId;
}
}
}
+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;
});
}),
);
}
}