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.
The UI thread
Section titled “The UI thread”- 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()orProcess.waitFor()there.- Check (code): event handlers, listeners and
Platform.runLaterbodies call noFiles.*,HttpClient.send,ProcessBuilder.start,waitFor,Future.get,joinorThread.sleep; that work runs on an executor or a virtual thread. - Reference: Editora
docs/performance.md§1.
- Check (code): event handlers, listeners and
- 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.
- Check (code): every executor task or thread body that ends in UI work wraps that work in
- 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 throughLatestOnly, and its result is applied only while that generation is still current, checked again inside therunLater. - Reference: Editora
git/GitService.java,search/SearchService.java,ui/LatestOnly.java(LatestOnlyTest).
- Check (code): each request takes a generation (
- 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…andnew Threadgets a name andsetDaemon(true), through a thread factory such asdaemon("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 aProcesssubclass overridesonExit().- Why: the common pool has one worker fewer than the machine has cores, so a few blocked waits
(
CompletableFuture.supplyAsyncof awaitFor) starve every other user of it. - Check (code): no
supplyAsyncorrunAsyncwithout an executor wraps a blocking call, and every class that extendsProcessoverridesonExit(). - Reference: Editora
process/ExitWatch.java,docs/gotchas.md. Editora’sDapManager.reportJavaExitstill waits up to 3 s for an exit code in asupplyAsyncon the common pool.
- Why: the common pool has one worker fewer than the machine has cores, so a few blocked waits
(
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.
Hot paths
Section titled “Hot paths”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
pendingflag, and text-driven work waits for typing to pause.- Check (code): a redraw request sets a
pendingflag and schedules one pass; listeners on text go through a debounce. - Reference: Editora
ui/FxThrottle.java.
- Check (code): a redraw request sets a
- PERF-07 MUST Streams (process output, logs, progress) reach the FX thread in batches at least 16 ms
apart, never one
runLaterper 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
ListVieworTableView, not aVBoxof nodes. - Reference: Editora
editor/highlight/HighlightPass.java,editor/minimap/MinimapRows.java.
- 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
- 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
SpanMergerineditor/highlight/TextMateHighlighter.java,docs/gotchas.md.
- Check (code):
Memory and size
Section titled “Memory and size”- 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) andHUGE_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.
Start-up
Section titled “Start-up”- 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
ToolWindowsuppliers,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):
mainstarts the config read on its own thread beforelaunch. - Reference: Editora’s
config-prefetchthread inApp.java.
- Check (code):
- PERF-17 SHOULD The app ships precompiled stylesheets (
.bss) and an AOT cache trained on a real session.- Check (code): the build converts the
.cssfiles to.bssand runs a training launch for the AOT cache. - Reference: Editora
scripts/css2bss.java,scripts/aot_build.java; Termina’s and Mirada’sscripts/aot-train.sh.
- Check (code): the build converts the
Measure, don’t guess
Section titled “Measure, don’t guess”- 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
mainand the first paint record phase marks. - Reference:
scripts/measure-startup.shin Editora and Mirada; Editoraperf/Startup.java.
- Check (code): the repository has the script, and
- 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.nanoTimeinstrumentation 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