Skip to content
Pauta3.0.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.
    • Check (code): each request takes a generation (AtomicLong.incrementAndGet) or goes through LatestOnly, and its result is applied only while that generation is still current, checked again inside the runLater.
    • Reference: Editora git/GitService.java, search/SearchService.java, ui/LatestOnly.java (LatestOnlyTest).
  • 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.
    • Check (code): a reader thread appends to a buffer that the FX thread drains, with a minimum interval between drains.
    • Reference: Editora process/OutputPump.java (MIN_DRAIN_INTERVAL_MILLIS), ui/ConsoleAppender.java.
  • 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).
    • Check (code): a listener on text, scroll or a timer re-processes the edited range or the visible rows, never the whole document or list; growing lists are ListView or TableView, not a VBox of nodes.
    • Reference: Editora editor/highlight/HighlightPass.java, editor/minimap/MinimapRows.java.
  • 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.
    • Check (code): applyCss() is called only on small nodes; style classes are not toggled per keystroke.
    • Reference: Editora SpanMerger in editor/highlight/TextMateHighlighter.java, docs/gotchas.md.
  • PERF-11 MUST Everything that grows is bounded: logs, histories, consoles, caches, undo. The newest is kept, with a note of what was cut.
    • Check (test): each such store has a test that fills it past its cap and finds the oldest dropped.
    • Reference: Editora ui/MessageLog.java (200, MessageLogTest), ui/DebugLog.java (DebugLogTest), test/OutputCap.java.
  • PERF-12 MUST 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.
    • Check (code): the loader compares the size against named thresholds before reading the content.
    • Reference: Editora EditorBuffer.LARGE_FILE_BYTES (5 MB) and HUGE_FILE_BYTES (50 MB), ui/LoadHeapGuard.java (LoadHeapGuardTest).
  • PERF-13 MUST A closed window releases what it held: listeners, timers, executors, file watchers, native resources.
    • Check (test): a test opens and closes windows and checks nothing is left running.
    • Reference: Editora FxWindowFixture.dispose (FxWindowFixtureLifecycleFxTest), ClosedLspManagers.
  • PERF-14 MUST The first frame comes first: only what the first window shows is built before it; tool windows, panels and pages build on first open.
    • Check (test): a test opens a window and finds no closed tool window’s panel built before the first paint.
    • Reference: Editora’s lazy ToolWindow suppliers, LazyToolWindowsFxTest.
  • PERF-15 MUST What nobody waits for starts after the first frame has painted: the update check, extra fonts, indexes and caches.
    • Check (test): a test finds the deferred work not started before the first paint.
    • Reference: Editora ui/UpdateCheckScheduler.java, Fonts.loadRemainingAfterNextPaint (UpdateCheckSchedulerTest, FontsDeferredLoadFxTest, StartupDeferralFxTest).
  • PERF-16 SHOULD Config is read off the FX thread, before the toolkit needs it.
    • Check (code): main starts the config read on its own thread before launch.
    • Reference: Editora’s config-prefetch thread in App.java.
  • PERF-17 SHOULD The app ships precompiled stylesheets (.bss) and an AOT cache trained on a real session.
    • Check (code): the build converts the .css files to .bss and runs a training launch for the AOT cache.
    • Reference: Editora scripts/css2bss.java, scripts/aot_build.java; Termina’s and Mirada’s scripts/aot-train.sh.
  • 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 3.0.0 · · Changelog · This page in the latest edition