Skip to content

Local engineering spec for the 0.8.x modernization line. Structural, concurrency-sensitive, protocol-adjacent (touches the published file set) — do behind the parity harness, not as RC-stabilization work.

REF-058 - Async known-file and shared-file startup load to unblock the UI thread

Problem (profiling evidence)

Diagnostics-build startup profiling against a real, heavy profile (known.met ~40 MB, 40,558 shared files) shows startup is dominated by two synchronous, UI-thread-serialized, disk-I/O-bound loads in InitInstance:

  • Construct CKnownFileList (known.met/cancelled.met): ~7.8 s warm / ~10 s cold
  • Construct CSharedFileList (share cache/scan + 40,558-row eager bind): ~6 s

Total startup.complete ~17 s warm / ~25 s cold; the main window is not interactive until then. Evidence: EMULEBB_WORKSPACE_OUTPUT_ROOT\reports\startup-profile\20260611T090338Z\.

The companion finding from REF-057: startup is disk-saturated, so parallelizing a single small read (geolocation) does not help — it just contends. The win must come from reading/parsing less or deferring the data-model population, not from adding parallel reads.

Direction (not yet designed)

  • Bring the main window up interactive first, then load the known/shared metadata off the UI thread with an explicit "loading" state, adopting results on the UI thread (single-writer discipline), repainting lists as data arrives.
  • Reduce per-record allocation churn in CKnownFile/CSharedFileList (raw new/delete; see REF-055).
  • Avoid the eager 40,558-row Shared Files bind during OnInitDialog; populate the model lazily / incrementally.

Constraints

  • Preserve eD2K/Kad wire semantics and the published file set; collect parity evidence (community baseline / tracing harness) since load ordering affects what is advertised at startup and when.
  • High concurrency risk (the cross-thread CList/ownership class behind the recent UAF wave); land incrementally behind tests.

REF-055 (RAII/structure), REF-057 (geo, deferred), FEAT-072, FEAT-100, FEAT-076, FEAT-034.

Acceptance criteria

  • Main window interactive well before known/shared metadata finishes loading.
  • No eD2K/Kad protocol or published-set drift (parity evidence attached).
  • Each slice lands reviewed and test-covered on the 0.8.x line.