Skip to content
Pauta4.1.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.

  • 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.1.0 · · Changelog · This page in the latest edition