Sub-Frame Performance & Benchmarks

Kalc is engineered to deliver instantaneous feedback as you type. While modern desktop computers boast multi-core Apple Silicon chips and 120Hz ProMotion displays, many calculator and notepad apps feel sluggish because they run on heavy web views or re-parse entire documents from scratch on every keystroke.

Kalc guarantees sub-frame responsiveness through a dedicated Swift actor, incremental line caching, and native memory management.

---

The 8.0 ms Frame Budget

On a 120Hz ProMotion display, a single display frame renders every 8.33 milliseconds. For an editor to feel perfectly responsive, document recalculation must finish within this window so that results align without dropping frames.

Kalc targets a strict engineering budget:

Complete incremental recalculation of a 1,000-line document must execute in $\le 8.0\text{ ms}$ (p95) on Apple Silicon.

Benchmark Results (1,000 Lines)

Testing with the standardized 1000_lines_benchmark.kalc fixture (combining variable bindings, dimensional math, currency conversions, percentages, block aggregates, and math functions):

Metric	Target Engineering Budget	Observed Baseline (Apple Silicon)	Margin
Incremental Recalculation (p95)	$\le 8.0\text{ ms}$	$0.84\text{ ms}$ median	$9.5\times$ faster
Incremental Recalculation (p50)	$\le 3.0\text{ ms}$	$0.52\text{ ms}$ median	$5.7\times$ faster
Cold Startup Recalculation	$\le 50.0\text{ ms}$	$14.2\text{ ms}$	$3.5\times$ faster
Resident Memory (RSS)	$\le 45.0\text{ MB}$	$14.1\text{ MB}$	$3.1\times$ lower

---

Architectural Pillars of Speed

1. The ExecutionCoordinator Actor

Document evaluation is isolated inside ExecutionCoordinator, a Swift actor with compile-time strict concurrency checking. It manages document snapshot versions, guarantees monotonic revision order, and dispatches computation to background threads without blocking the @MainActor UI thread.

2. Monotonic Snapshots & Task Cancellation

Every keystroke in KalcTextView increments an atomic revision counter and constructs an immutable DocumentSnapshot(revision:lines:).

• When rapid typing occurs, in-flight calculation tasks for older revisions are immediately cancelled via inFlightTask?.cancel().
• Obsolete intermediate states are discarded before wasting CPU cycles.

3. Incremental Line Caching

Rather than re-evaluating every line in a document when you type on line 42, Kalc maintains an internal cache (lineCache: [Int: CachedLine]):

• Unchanged lines above the edit point are retrieved directly from cache.
• Variables exported by those cached lines are re-registered in Scope in constant time ($O(1)$).
• Tokenization, Pratt AST construction, and math evaluation are executed only for dirty lines.

graph TD
    A[Keystroke in KalcTextView] --> B[Create DocumentSnapshot rev N]
    B --> C{Cancel in-flight task?}
    C --> D[Dispatch to ExecutionCoordinator]
    D --> E[Check lineCache for line i]
    E -- Cache Hit --> F[Re-export cached variables to Scope]
    E -- Cache Miss --> G[Classify -> Tokenize -> Parse AST -> Evaluate]
    G --> H[Store in lineCache]
    F --> I[Assemble DocumentEvaluationResult]
    H --> I
    I --> J[MainActor UI Delivery & Flash Animation]

---

Memory Footprint & Native Frameworks

Many modern desktop utilities wrap Electron or Chromium, demanding 200 MB to 600 MB of resident RAM just to display a calculator.

Kalc is compiled directly to native ARM64 machine instructions:

• Zero Third-Party Libraries: Depends strictly on Apple's system frameworks (Foundation, AppKit, TextKit 2, Carbon, Network, JavaScriptCore).
• Peak RSS of 14.1 MB: Consumes a fraction of system memory, allowing it to remain permanently open in your menu bar without impacting battery life or system responsiveness.

---

Running the Benchmark

The repository includes a dedicated benchmark executable:

# Run inside apps/macos
swift run kalc-benchmark

The runner profiles 1,000 synthetic lines over repeated cold and warm passes, measuring median latency, p95/p99 variance, memory allocation, and concurrency stability.