Skip to content

Commit 1afcf1e

Browse files
Merge the opt-in incremental collector
Brings in HXCPP_GC_INCREMENTAL from feature/incremental-gc on top of the 6.0.0 batches. Where they met in Immix.cpp, both sides are kept: FreeLarge still refuses a block object before the incremental check, the stack scan marks a large object from a pointer into it before either marking path, InternalCollectBytes passes its options in a register inside the incremental retry loop, and the trace cut resets beside IncrementalScanned. An incremental collection now names the thread that owns a finalizer's exception before its guard resumes the other threads, so the exception is thrown there as in the other modes, and the dropped recycle cache is released at the end of every collection. The collector stays off by default. #372's throughput and finishing-pause gates are still open.
2 parents 8c17283 + 6b621ec commit 1afcf1e

46 files changed

Lines changed: 2634 additions & 30 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/main.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -224,6 +224,20 @@ jobs:
224224
working-directory: test/gc_stress
225225
run: haxe compile.hxml -D HXCPP_M64 -D HXCPP_SANITIZE=${{ matrix.sanitize }} && bin/Stress 10
226226

227+
# The new collector has its own deterministic scheduling and barrier paths.
228+
- name: Run incremental GC regressions
229+
if: ${{ !cancelled() && steps.setup.outcome == 'success' }}
230+
working-directory: test/regression
231+
run: |
232+
for test in GcMutationRoots GcContainerMutation IncrementalGcSlices IncrementalGcContainers IncrementalGcFinishBoundary GcWeakMapChain GenerationalFinalizerLifecycle GenerationalLargeBufferLifecycle; do
233+
(cd "$test" && haxe -main Main -cpp bin -lib hxcpp -D HXCPP_M64 -D HXCPP_GC_INCREMENTAL -D HXCPP_GC_INCREMENTAL_VERIFY -D HXCPP_GC_INCREMENTAL_TEST -D HXCPP_SANITIZE=${{ matrix.sanitize }} && bin/Main > out.txt && diff <(tr -d '\r' < stdout.txt) <(tr -d '\r' < out.txt))
234+
done
235+
236+
- name: Run incremental GC stress
237+
if: ${{ !cancelled() && steps.setup.outcome == 'success' }}
238+
working-directory: test/gc_stress
239+
run: haxe compile.hxml -lib hxcpp -D HXCPP_M64 -D HXCPP_GC_INCREMENTAL -D HXCPP_GC_INCREMENTAL_VERIFY -D HXCPP_SANITIZE=${{ matrix.sanitize }} && bin/Stress 10 8 2012663045
240+
227241
- name: Show the sanitizer reports
228242
if: ${{ !cancelled() }}
229243
run: cat /tmp/sanitizer/report.* 2>/dev/null || echo "No sanitizer reports"

‎.github/workflows/test.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,6 +383,49 @@ jobs:
383383
done
384384
[ -z "$failed" ] || { echo "Failed modes:$failed"; exit 1; }
385385
386+
incremental:
387+
if: inputs.scope == 'full' && startsWith(inputs.haxe, '4.3.')
388+
runs-on: ${{ inputs.os }}
389+
name: incremental gc
390+
timeout-minutes: 90
391+
defaults:
392+
run:
393+
shell: bash
394+
steps:
395+
- name: checkout
396+
uses: actions/checkout@v7
397+
- name: setup
398+
uses: ./.github/workflows/setup
399+
with:
400+
haxe: ${{ inputs.haxe }}
401+
- name: deterministic phases and semantics
402+
working-directory: test/regression
403+
run: |
404+
failed=""
405+
for test in GcMutationRoots GcContainerMutation IncrementalGcSlices IncrementalGcContainers IncrementalGcFinishBoundary IncrementalGcVerifier GcWeakMapChain GenerationalFinalizerLifecycle GenerationalLargeBufferLifecycle; do
406+
echo "::group::incremental gc: $test"
407+
# The lifecycle fixtures' hxml selects generational mode; compile
408+
# the same Main with incremental mode here instead.
409+
if ! (cd "$test" && haxe -main Main -cpp bin -lib hxcpp -D HXCPP_GC_INCREMENTAL -D HXCPP_GC_INCREMENTAL_VERIFY -D HXCPP_GC_INCREMENTAL_TEST -D $HXCPP_ARCH_FLAG && bin/Main > out.txt && diff <(tr -d '\r' < stdout.txt) <(tr -d '\r' < out.txt)); then
410+
failed="$failed $test"
411+
echo "::error::incremental gc failed: $test"
412+
fi
413+
echo "::endgroup::"
414+
done
415+
[ -z "$failed" ] || { echo "Failed tests:$failed"; exit 1; }
416+
- name: incremental stress
417+
if: ${{ !cancelled() }}
418+
working-directory: test/gc_stress
419+
run: |
420+
haxe compile.hxml -lib hxcpp -D HXCPP_GC_INCREMENTAL -D HXCPP_GC_INCREMENTAL_VERIFY -D $HXCPP_ARCH_FLAG
421+
bin/Stress 30 8 2012663045
422+
- name: incremental stress (big blocks)
423+
if: ${{ !cancelled() }}
424+
working-directory: test/gc_stress
425+
run: |
426+
haxe compile.hxml -lib hxcpp -D HXCPP_GC_INCREMENTAL -D HXCPP_GC_INCREMENTAL_VERIFY -D HXCPP_GC_BIG_BLOCKS -D $HXCPP_ARCH_FLAG
427+
bin/Stress 30 8 1337
428+
386429
cppia:
387430
if: inputs.scope == 'full'
388431
runs-on: ${{ inputs.os }}

‎BENCHMARKS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,7 @@ These numbers are from one Windows machine; Linux and macOS results are still to
9797
| `alloc_strings` | Int-to-String conversion plus a concatenation per string |
9898
| `alloc_arrays` | Arrays of 1 to 64 Ints grown by `push`, plus a 256 KB buffer every 4000 arrays |
9999
| `gc_pauses` | Collection pauses as the program sees them: a large live graph stays reachable while the program allocates in fixed work units, and each unit's duration is recorded. The tail holds the units that included a collection |
100+
| `gc_frames` | 2,000 frames over 150,000 retained entities with graph and inventory mutation, temporary particle chains and event strings, fixed-size spatial cells and periodic allocation bursts. Records frame latency and checks retained payloads. Uses automatic GC without frame hooks or sleeps |
100101
| `map_int` | `IntMap`: on a fresh map, N sets, N hits, N misses, N/2 removes, then iterating the N/2 values left |
101102
| `map_string` | `StringMap`, the same cycle |
102103
| `map_object` | `ObjectMap`, the same cycle |

‎Changes.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,7 @@ libhxcpp 6.0.0 (unreleased)
7676
* Fixed Gc.trace without path printing overflowing the native stack on a deep graph, such as a linked list of 100,000 nodes, in debug builds: it marked each object by recursing into it. Counting now marks from the mark stack, on one thread so each instance counts once; printing paths still recurses (libhxcpp #389)
7777
* Fixed a bound method or callback adapter held only by a WeakRef having its finalizer run while its receiver lived: the collection chose what to finalize before deciding that the weak reference keeps such a callback, so WeakRef.get still returned it afterwards. Callbacks a weak reference keeps are now marked before finalizers are chosen (libhxcpp #376)
7878
* Fixed a large object, of 4,000 bytes or more, held only by native code through the address of one of its fields being freed: the stack scan recognized a large allocation only by its exact start, while for a smaller object it already accepted a pointer up to 64 bytes in (32 on 32-bit). Large allocations now take the same allowance (libhxcpp #373)
79+
* Added an opt-in incremental marking collector for native Haxe 4 C++ builds (`-lib hxcpp -D HXCPP_GC_INCREMENTAL`), with automatic allocation pacing, optional `hxcpp.gc.Incremental` scheduling hooks, resumable array and map scans, an independent verifier and deterministic regression tests. The existing collector remains the default. Slice budgets are targets, and synchronous completion and memory pressure can still cause longer pauses; see docs/IncrementalGc.md
7980
* Emscripten programs let memory grow and get a 5 MB stack by default. They linked with Emscripten's fixed 16 MB of memory, which aborts with "Aborted(OOM)" as soon as a program holds more, and since Emscripten 3.1.27 a 64 KB stack, which Haxe recursion and the pointers that spill-pointers keeps on the stack soon overflow. HXCPP_LINK_NO_MEMORY_GROWTH and HXCPP_LINK_NO_STACK_SIZE restore Emscripten's settings, and HXCPP_LINK_STACK_SIZE sets another size
8081
* Fixed converting a long or a size_t to Dynamic failing to compile on Emscripten, where long is 32 bits but not int, as an Int default of -2147483648 does (HaxeFoundation/hxcpp#621)
8182
* Fixed cppia hosts built with HXCPP_DEBUGGER failing to compile on Emscripten, which has no cppia JIT: the debugger's frame reader asked whether a function was jitted through a field that only exists with the JIT
Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Incremental GC development measurements
2+
3+
These results compare the existing libhxcpp collector with the experimental incremental mode in the same source tree. They do not replace the stock-hxcpp comparison in [BENCHMARKS.md](../../../BENCHMARKS.md). Both collectors use the same benchmark sources, optimized compiler settings and payload checks.
4+
5+
The raw process results, sample times, latency summaries, checksums, peak working sets, reserved heap sizes and incremental counters are in [windows-x64-20261026.json](windows-x64-20261026.json). The containing commit identifies the implementation; the JSON also records the base revision and source hashes.
6+
7+
## Results
8+
9+
Elapsed time is the median of the 15 measured samples. Latency columns show the largest per-process p99.9 and the largest observed work-unit duration across the three processes; the p99.9 column is not a pooled percentile. Memory columns show the largest process value.
10+
11+
| Workload | Collector | Elapsed, ms | Worst p99.9, ms | Maximum, ms | Peak RSS, MiB | Reserved heap, MiB |
12+
| --- | --- | ---: | ---: | ---: | ---: | ---: |
13+
| `gc_frames` | Existing | 240.246 | 7.742 | 9.728 | 128.76 | 115.36 |
14+
| `gc_frames` | Incremental | 294.961 | 0.969 | 1.858 | 131.98 | 118.29 |
15+
| `gc_pauses` | Existing | 145.429 | 5.055 | 8.289 | 135.29 | 121.55 |
16+
| `gc_pauses` | Incremental | 256.843 | 2.718 | 5.232 | 135.52 | 122.51 |
17+
18+
All six `gc_frames` processes returned checksum 1106626610; all six `gc_pauses` processes returned 458711266. Incremental mode reduced tail latency on these workloads, with 22.8% more elapsed time for `gc_frames` and 76.6% more for `gc_pauses`. That corresponds to 18.5% and 43.4% less throughput, respectively. Neither meets the proposed maximum 10% throughput loss.
19+
20+
The largest budgeted collector invocation was 1.346 ms in `gc_frames` and 1.783 ms in `gc_pauses`, against a requested 0.5 ms. Cumulative unbudgeted maxima were 13.553 ms and 9.971 ms, respectively, including explicit collections outside measured frames. These results do not establish a sub-millisecond collector or eliminate synchronous interruptions.
21+
22+
## Protocol
23+
24+
- Windows x64, AMD Ryzen 9 9950X, Haxe 4.3.7 and MSVC 19.44.35213.
25+
- Default block size, existing collector defaults versus `HXCPP_GC_INCREMENTAL` with its default 0.5 ms target and 1 ms preferred interval.
26+
- No `HXCPP_GC_INCREMENTAL_VERIFY`, `HXCPP_GC_INCREMENTAL_TEST`, scriptable mode or explicit engine scheduling hooks.
27+
- Three processes per workload and collector, two warmups and five measured samples per process. Collector order alternates between processes. Compilation, stress and sanitizer runs finished before measurement.
28+
- `gc_frames` retains 150,000 entities and runs 2,000 frames per sample. Frame timing includes graph and inventory changes, temporary particles and event strings, fixed-size spatial cells and periodic bursts. Payload validation runs after the frame loop and is included in elapsed sample time.
29+
- `gc_pauses` retains a large graph and records 3,000 allocation work units per sample. A work unit is not a game frame or an isolated GC pause.
30+
- The harness requests a full collection before each sample, outside its timed section. Cumulative GC counters include setup, warmups, these explicit collections and validation. Their maxima cannot be presented as maxima of GC work inside measured frames.
31+
- Checksums must agree across all processes of a workload. The JSON contains elapsed sample times and per-process latency summaries, rather than a trace of individual frames.
32+
33+
## Reproduction
34+
35+
After pointing haxelib at this checkout as described in CONTRIBUTING.md, build each mode sequentially:
36+
37+
```sh
38+
haxe -cp bench/src -main Main -cpp build/gc-default -lib hxcpp -D HXCPP_M64
39+
haxe -cp bench/src -main Main -cpp build/gc-incremental -lib hxcpp -D HXCPP_M64 -D HXCPP_GC_INCREMENTAL
40+
```
41+
42+
For each workload, run the following pair three times, reversing the order in the second pair. On Windows the executable is `Main.exe`.
43+
44+
```sh
45+
build/gc-default/Main gc_frames --warmup 2 --samples 5
46+
build/gc-incremental/Main gc_frames --warmup 2 --samples 5
47+
build/gc-default/Main gc_pauses --warmup 2 --samples 5
48+
build/gc-incremental/Main gc_pauses --warmup 2 --samples 5
49+
```
50+
51+
## Correctness validation
52+
53+
Local Windows validation includes all nine phase and lifecycle fixtures listed in [IncrementalGc.md](../../../docs/IncrementalGc.md), with the independent verifier and deterministic controls, at normal and big block sizes. Each block size also passed three 30-second stress runs with eight threads and seeds 2012663045, 1337 and 8675309. The full runtime suite passed 1,100 assertions with incremental verification and big blocks. The new slice, container and finishing fixtures also pass with the existing collector, and the container and finishing fixtures pass in single-threaded incremental builds.
54+
55+
Linux under WSL, Haxe 4.3.3 and GCC 13.3 passed ASan and UBSan builds of the slice, container and finishing fixtures, plus a 30-second stress run with eight threads under each sanitizer. Leak detection is disabled because these runs exercise the runtime's conservative stack scanning configuration. They are not leak measurements. The final GCC define matrix passed all 79 configurations, including incremental, verification/test and single-threaded variants at both block sizes.
56+
57+
The independent verifier fixture deliberately omits a reachable descendant's mark in a child process and requires rejection. The epoch recovery assertion failed before the recovery fix, and the allocation cursor assertion failed before preserving allocator ranges across partial slices.
58+
59+
The isolated haxelib installation, setup, update and off checks passed on Windows and Linux. Their synthetic package includes the configuration macro referenced by `extraParams.hxml`.
60+
61+
Local TSan did not reach a usable test run: the installed GCC runtime rejected the repository suppression syntax and, without suppressions, failed under WSL before the workload ran. TSan and other platform results remain for CI. CI configuration includes incremental regressions and stress in the sanitizer jobs and a native incremental job on supported Haxe 4 configurations.
62+
63+
## Remaining gates
64+
65+
This is experimental. The throughput target in [#372](https://github.com/openfl/libhxcpp/issues/372) is still open. Weak closure, finalizers, reclamation, root capture, thread rendezvous and forced completion can exceed the slice target. Longer soaks, additional memory-pressure and native-integration coverage, pause distributions for all stopped threads, progress and metadata high-water counters, and cross-platform results are still needed before considering a default change.

0 commit comments

Comments
 (0)