docs: document strict 2.4-A plus GC companion A/B

2026-09-02 23:44:19 +02:00
parent f72686f27a
commit 9d5d7bd0d6
1 changed files with 35 additions and 7 deletions
@@ -1,14 +1,42 @@
 # WeirdPerformance 2.4-B — GC Safe Sweep test

-This is an A/B test companion for the validated WeirdPerformance 2.4-A DLL.
+Strict A/B experiment for WoW 1.12.1 build 5875.

- `weirdperformance.dll` = unchanged 2.4-A baseline
- `weirdperformance_gc24b.dll` = only experimental delta: incremental Lua `rootgc` sweep
+## Baseline

-Load both DLLs. Do not replace the 2.4-A DLL with the companion.
+Keep the validated 2.4-A binary **unchanged**:

-WoW's native mark, userdata/string sweep, shrink, finalizers, and the 2.4-A hybrid allocator remain in place. Only the main rootgc sweep is split into 50,000-object chunks.
+- `weirdperformance.dll`
+- SHA-256: `d35168ae06c19087ef9b7c68918a054640396dfbfcef0664e18e9372284b5eef`

-Restart safety enters native-GC passthrough before `CGGameUI_Shutdown`, reconnects any split list first, and re-enables the experiment only after `Player_LoadScriptFunctions`. The luaC_link birth-mark byte is ownership-checked; if it cannot be acquired, that cycle stays native.
+## B variant

-Scope: WoW 1.12.1 build 5875 test only.
+Add:
+
+- `weirdperformance_gc24b.dll`
+
+The companion changes **only Lua GC behavior**. It does not replace or rebuild the validated 2.4-A DLL.
+
+The implementation is based on the historical pre-generational incremental sweep: WoW keeps its native mark, userdata/string sweep, memory shrink and finalizers. Only the main `rootgc` sweep is split into 50,000-object chunks.
+
+## Safety changes versus the old experiment
+
+- hooks only `luaC_collectgarbage` and `lua_close`;
+- no overlap with the lifecycle hooks referenced by the validated 2.4-A binary;
+- any fragmented sweep is reconnected before native `lua_close` destroys the Lua state;
+- GC calls made from inside `lua_close` stay native;
+- the birth-mark byte is ownership checked and restored only while still owned;
+- a changed Lua `global_State` forces native fallback rather than reconnecting stale pointers;
+- hook installation is transactional;
+- no generational age bitmap, no write barriers, no GC tuning, no profiling/RDTSC.
+
+## Installation for the test
+
+Keep both DLLs next to WoW and list both in `dlls.txt`:
+
+```text
+weirdperformance.dll
+weirdperformance_gc24b.dll
+```
+
+Removing `weirdperformance_gc24b.dll` returns you exactly to the validated 2.4-A baseline.