Skip to content
Pauta4.3.0

Performance

A desktop app is judged by how it feels under the hand: a key that lags or a window that hangs while it reads a file is a defect, not a slow feature. These rules come from Editora’s docs/performance.md, the contract every change on a hot path there must honor.

Rules on this page 22
IDLevelRule
The UI thread
PERF-01MUST
Never block the JavaFX application thread. No file or network I/O, no process start or wait, no parsing, searching, hashing or JSON of any size on it, and no Thread.sleep, Future.get(), join() or Process.waitFor() there.
PERF-02MUST
Touch the scene graph only on the FX thread. Background work hands its result back with Platform.runLater; nothing else creates, changes or reads live nodes.
PERF-03MUST
A background result is applied under a generation guard, so an answer to an old request never overwrites a newer one.
PERF-04SHOULD
Every thread is named and is a daemon.
PERF-05MUST
Blocking work stays off the common ForkJoinPool, and a Process subclass overrides onExit().
Hot paths
PERF-06MUST
Redraws are coalesced to at most one per pulse with a pending flag, and text-driven work waits for typing to pause.
PERF-07MUST
Streams (process output, logs, progress) reach the FX thread in batches at least 16 ms apart, never one runLater per line.
PERF-08MUST
Work only on what is visible and only on what changed: no O(document) or O(list) work per keystroke, scroll or tick. Anything that can grow is shown in a virtualized control (ListView, TableView, a fixed cell size).
PERF-09SHOULD
A hot path allocates little: it reuses buffers and arrays, and caches data a repaint only reads.
PERF-10SHOULD
CSS stays cheap: no applyCss() on a large subtree, stable style classes, and spans of the same style merged before they are applied.
Memory and size
PERF-11MUST
Everything that grows is bounded: logs, histories, consoles, caches, undo. The newest is kept, with a note of what was cut.
PERF-12MUST
Large inputs are guarded by size and shape before they load: expensive features turn off past one threshold, the input opens read-only or capped past another, and what will not fit the free heap is refused.
PERF-13MUST
A closed window releases what it held: listeners, timers, executors, file watchers, native resources.
Start-up
PERF-14MUST
The first frame comes first: only what the first window shows is built before it; tool windows, panels and pages build on first open.
PERF-15MUST
What nobody waits for starts after the first frame has painted: the update check, extra fonts, indexes and caches.
PERF-16SHOULD
Config is read off the FX thread, before the toolkit needs it.
PERF-17SHOULD
The app ships precompiled stylesheets (.bss) and an AOT cache trained on a real session.
Measure, don’t guess
PERF-18SHOULD
Every change on a hot path says what it costs in its pull request: added FX-thread work, allocation per keystroke or scroll, extra layout passes, memory. “Negligible” is an answer; no answer is not.
PERF-19SHOULD
Start-up is measured by a script that takes the median of several cold launches, and by phase marks in the app.
PERF-20SHOULD
The app can sample its FX thread when something stalls.
PERF-21SHOULD
Each hot path that once regressed keeps a headless test.
PERF-22SHOULD
A suspected regression gets a number before and after, from temporary System.nanoTime instrumentation if nothing better exists.
  • PERF-01 MUST Never block the JavaFX application thread. No file or network I/O, no process start or wait, no parsing, searching, hashing or JSON of any size on it, and no Thread.sleep, Future.get(), join() or Process.waitFor() there.
    • Check (code): event handlers, listeners and Platform.runLater bodies call no Files.*, HttpClient.send, ProcessBuilder.start, waitFor, Future.get, join or Thread.sleep; that work runs on an executor or a virtual thread.
    • Reference: Editora docs/performance.md §1.
  • PERF-02 MUST Touch the scene graph only on the FX thread. Background work hands its result back with Platform.runLater; nothing else creates, changes or reads live nodes.
    • Check (code): every executor task or thread body that ends in UI work wraps that work in Platform.runLater.
    • Reference: every Editora service, for example git/GitService.java.
  • PERF-03 MUST A background result is applied under a generation guard, so an answer to an old request never overwrites a newer one.
  • PERF-04 SHOULD Every thread is named and is a daemon.
    • Why: a thread dump then says what is running, and a stray worker never keeps the app alive after its last window closes.
    • Check (code): every Executors.new… and new Thread gets a name and setDaemon(true), through a thread factory such as daemon("my-feature"); virtual threads are daemons already.
    • Reference: Editora daemon("my-feature") in the shape below, terminal/TerminalExecutors.java.
  • PERF-05 MUST Blocking work stays off the common ForkJoinPool, and a Process subclass overrides onExit().
    • Why: the common pool has one worker fewer than the machine has cores, so a few blocked waits (CompletableFuture.supplyAsync of a waitFor) starve every other user of it.
    • Check (code): no supplyAsync or runAsync without an executor wraps a blocking call, and every class that extends Process overrides onExit().
    • Reference: Editora process/ExitWatch.java, docs/gotchas.md. Editora’s DapManager.reportJavaExit still waits up to 3 s for an exit code in a supplyAsync on the common pool.

The canonical shape, used by every Editora service:

private final ExecutorService exec = Executors.newSingleThreadExecutor(daemon("my-feature"));
private final AtomicLong gen = new AtomicLong();
void request(String input, Consumer<Result> onResult) {
long mine = gen.incrementAndGet();
exec.submit(() -> {
Result r = computeOffThread(input); // heavy work, off the FX thread
if (mine == gen.get()) { // superseded? drop it
Platform.runLater(() -> {
if (mine == gen.get()) onResult.accept(r);
});
}
});
}

For one-off blocking calls (reading a file, stat-ing a path, starting a process), a virtual thread (Thread.ofVirtual().start(…)) is enough; the result still comes back through Platform.runLater.

Each app names its hot paths: what runs on every keystroke, scroll pulse or progress tick. In Editora they are typing, scrolling, highlighting, the overlays and the gutter. In Torrenta they are the transfer table’s refresh, in Termina the terminal grid, in Mirada stepping between images.

  • PERF-06 MUST Redraws are coalesced to at most one per pulse with a pending flag, and text-driven work waits for typing to pause.
    • Check (code): a redraw request sets a pending flag and schedules one pass; listeners on text go through a debounce.
    • Reference: Editora ui/FxThrottle.java.
  • PERF-07 MUST Streams (process output, logs, progress) reach the FX thread in batches at least 16 ms apart, never one runLater per line.
  • PERF-08 MUST Work only on what is visible and only on what changed: no O(document) or O(list) work per keystroke, scroll or tick. Anything that can grow is shown in a virtualized control (ListView, TableView, a fixed cell size).
  • PERF-09 SHOULD A hot path allocates little: it reuses buffers and arrays, and caches data a repaint only reads.
    • Check (code): the per-frame and per-keystroke code allocates no new arrays or images when the size has not changed.
    • Reference: Editora editor/minimap/Minimap.java (the snapshot image reused at the same size), MinimapRows.java.
  • PERF-10 SHOULD CSS stays cheap: no applyCss() on a large subtree, stable style classes, and spans of the same style merged before they are applied.
  • PERF-18 SHOULD Every change on a hot path says what it costs in its pull request: added FX-thread work, allocation per keystroke or scroll, extra layout passes, memory. “Negligible” is an answer; no answer is not.
    • Check (by hand): read the app’s recent pull requests that touch a hot path.
    • Reference: Editora docs/performance.md (its opening paragraph).
  • PERF-19 SHOULD Start-up is measured by a script that takes the median of several cold launches, and by phase marks in the app.
    • Check (code): the repository has the script, and main and the first paint record phase marks.
    • Reference: scripts/measure-startup.sh in Editora and Mirada; Editora perf/Startup.java.
  • PERF-20 SHOULD The app can sample its FX thread when something stalls.
    • Check (code): an environment variable or property turns on a sampler of the FX thread’s stack.
    • Reference: Editora perf/Startup.java (EDITORA_PERF_SAMPLE=1).
  • PERF-21 SHOULD Each hot path that once regressed keeps a headless test.
    • Check (test): the fix for a hot-path regression adds a headless test that fails on the old code.
    • Reference: Editora MinimapDeferredRenderFxTest.
  • PERF-22 SHOULD A suspected regression gets a number before and after, from temporary System.nanoTime instrumentation if nothing better exists.
    • Check (by hand): the pull request that fixes it states both numbers.
    • Reference: Editora docs/performance.md.

Pauta 4.3.0 · · Changelog · This page in the latest edition