SPB Git

Repository Public

performance.md 8.6 KB 114 lines markdown

1<!--2ORIX Docs3File: docs/development/performance.md4Description: The benchmark tool, the exact meaning of each metric, the measured results on file, and the optimisations present in the code.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# Performance910## The benchmark tool1112`Packages/ORIXDocsKit/Sources/orixbench/main.swift` is an executable target of the engine package. It builds a document in memory, times engine operations with `DispatchTime` and prints the results as JSON; nothing is estimated or extrapolated.1314```sh15cd Packages/ORIXDocsKit16swift run -c release orixbench 40 ../../docs/reports/benchmarks.json17```1819The first argument is the **number of chapters** (default 40), not a page count — the usage line in the file header says "pages≈N", but the value is passed to `makeDocument(chapters:)`. The optional second argument is the path of the JSON file to write. The `build` field records whether the binary was compiled in debug or release.2021### The generated document2223`makeDocument(chapters:)` produces a report-like document on US Letter with the "Academic" theme and numbered headings (levels 1–3):2425* a title, a table of contents and a page break;26* per chapter: a level-1 heading (with `pageBreakBefore` from the second chapter on) and four sections;27* per section: a level-2 heading and nine body paragraphs of 3 to 6 repetitions of one sentence; every fourth paragraph has a footnote, every fifth an italic sentence appended;28* even sections end with a 9 × 5 table and a caption with a sequence field; odd sections end with a centred display equation;29* a running header (level-1 heading text and document title) and a footer ("page / page count"), both with fields.3031So the benchmark exercises the multi-pass contents, running heads, footnote placement, tables, equations and the header/footer cache — not only plain text.3233### Metrics3435Times are milliseconds of wall-clock time for one run unless stated.3637| Key | Exact meaning |38|---|---|39| `document` | Size of the generated document: chapters, body blocks, words (`DocumentStatistics`), pages of the first layout, tables, footnotes, equations. |40| `layout_cold_ms` | One call to `Paginator.layout` on the whole document with a new, empty `LayoutCache` and no previous layout. Includes all pagination passes. |41| `layout_passes` | Number of passes that call needed ([pagination.md](../architecture/pagination.md#generated-blocks-and-convergence)). |42| `keystroke_model_edit_ms` | Median and 95th percentile, over 200 iterations, of `DocumentEditor.insertText` inserting one character (a space every seventh time) at offset 40 of a body paragraph in the middle of the document. The model edit only. |43| `keystroke_relayout_ms` | Median, 95th percentile and maximum, over the same 200 iterations, of the full `Paginator.layout` that follows each insertion, with the warm cache and the previous layout. This is the layout cost of a keystroke; it does not include drawing, undo registration or statistics. |44| `paragraph_break_at_start_relayout_ms` | One `insertParagraphBreak` at block 5 plus the full layout that follows: an edit near the start, after which every later block is flowed again. |45| `find_all_ms`, `find_matches` | `DocumentModel.findAll("schedule")` over the whole document, and the number of matches. |46| `numbering_ms` | One `Numbering(doc)`. |47| `pdf_export_ms`, `pdf_bytes`, `pdf_pages` | `PDFPublisher.publish` with default options (outline and tags on) and a new cache: includes its own print layout. Size and page count of the result. |48| `native_save_ms`, `native_bytes` | Encoding the `.orixdoc` container in memory (`DocumentConverter.export`); no disk write. |49| `native_open_ms` | Reading and verifying that container from memory. |50| `open_and_first_layout_ms` | `native_open_ms` plus a cold layout of a second read of the same data (the two parts are timed separately and added). |51| `docx_export_ms`, `docx_bytes` | DOCX export, which includes a print layout to compute page references. |52| `docx_import_ms` | Importing that DOCX. |53| `peak_memory_mb` | `ru_maxrss` of the process at the end, divided by 1,048,576: the peak resident size of the whole benchmark run, not of one operation. |54| `machine` | Active processor count and operating system version string. |5556What the tool does not measure: drawing a page on screen, scrolling, application launch, typing latency end to end in the app, or memory per document.5758## Results on file5960From `docs/reports/benchmarks.json`, verbatim. Machine as recorded in the file: 18 active cores, "Version 27.0 (Build 26A5425a)", `build`: `release`. Times in milliseconds.6162| Key | Value |63|---|---|64| `document.chapters` | 40 |65| `document.blocks` | 1884 |66| `document.words` | 177162 |67| `document.pages` | 487 |68| `document.tables` | 80 |69| `document.footnotes` | 320 |70| `document.equations` | 80 |71| `layout_cold_ms` | 436.577292 |72| `layout_passes` | 2 |73| `keystroke_model_edit_ms.median` | 0.12929099999999999 |74| `keystroke_model_edit_ms.p95` | 0.24675 |75| `keystroke_relayout_ms.median` | 14.027374999999999 |76| `keystroke_relayout_ms.p95` | 18.708082999999998 |77| `keystroke_relayout_ms.max` | 22.288083 |78| `paragraph_break_at_start_relayout_ms` | 13.884333 |79| `find_all_ms` | 19.820166 |80| `find_matches` | 6480 |81| `numbering_ms` | 1.024208 |82| `pdf_export_ms` | 1395.518458 |83| `pdf_bytes` | 3699661 |84| `pdf_pages` | 487 |85| `native_save_ms` | 51.645083999999997 |86| `native_bytes` | 137483 |87| `native_open_ms` | 59.917875000000002 |88| `open_and_first_layout_ms` | 452.972959 |89| `docx_export_ms` | 454.57129099999997 |90| `docx_bytes` | 42605 |91| `docx_import_ms` | 116.222583 |92| `peak_memory_mb` | 338 |9394A second file, `docs/reports/benchmarks-100-pages.json`, holds a run with 8 chapters on the same machine and build (380 blocks, 35434 words, 98 pages): `layout_cold_ms` 99.381666999999993, `keystroke_relayout_ms.median` 2.287166, `pdf_export_ms` 263.617459, `peak_memory_mb` 88.5625; the other keys are in the file.9596These are single runs of a synthetic document on one machine. They show orders of magnitude and how costs scale between the two sizes; they are not guarantees for other documents or hardware.9798## Optimisations present in the code99100| Optimisation | Where | What it avoids |101|---|---|---|102| Paragraph layout cache | `LayoutCache` in `DocLayout/DocumentLayout.swift` | Typesetting a paragraph again when the paragraph and its environment are unchanged. After a keystroke only the edited paragraph is typeset (plus any whose number, page reference or neighbouring float changed); every pass still flows all blocks. See [layout-engine.md](../architecture/layout-engine.md#the-layout-cache). |103| Content-keyed header/footer cache | `LayoutCache.repeated` | Typesetting the same header or footer paragraph once per page: one layout per distinct field content and width. |104| Previous layout as the starting point | `Paginator.layout(…, previous:)`, used by `DocumentSession.relayout()` | A second pagination pass when page references did not move: the references of the previous layout seed the first pass. |105| Value-type snapshots | `DocumentModel` (structs, copy-on-write arrays); `DocumentSession.perform`, `ModelStore` | Deep copies for undo and for background saving: a snapshot shares the storage of everything the edit did not touch. |106| Font, math and image caches | `FontCache`, `MathRenderer` (`NSCache`, 4,000 formulas), `ImageStore` (decoded images, 512 MB limit) | Recreating fonts, re-typesetting formulas and decoding images on every layout or draw. |107| Lazy page drawing | `EditorCanvasView.draw(_:)` | Rendering pages outside the dirty rectangle: only pages whose frame intersects it are drawn, and the caret blink invalidates only the caret's rectangle. |108| Per-paragraph spelling cache | `SpellingCache` in `EditorCanvasView.swift` | Asking `NSSpellChecker` again for a paragraph whose text did not change. |109| Debounced statistics | `DocumentSession.scheduleStatistics()` | Counting words on every keystroke: the count runs 0.35 s after the last change. |110| Debounced, lazy thumbnails | `PageThumbnailStore` in `Sidebar/PagesPanel.swift` | Rendering every page thumbnail after every edit: visible thumbnails are re-rendered 0.5 s after the last layout change on a utility-priority task, others when they scroll into view, and at most 160 are kept. |111| Coalesced undo | `DocumentSession.perform(_:coalesce:_:)` | One undo registration per keystroke during a burst of typing. |112113Not present: incremental pagination (resuming the flow from the edited block), background layout (layout runs on the main thread inside `documentChanged()`), and partial redraw after an edit (`layoutChanged` invalidates the whole canvas view; the visible pages are redrawn).114
Files main
Menu

Theme