diff --git a/bench/results/incremental-gc/README.md b/bench/results/incremental-gc/README.md index b016eb4d7..538c97201 100644 --- a/bench/results/incremental-gc/README.md +++ b/bench/results/incremental-gc/README.md @@ -90,4 +90,4 @@ Local TSan did not reach a usable test run: the installed GCC runtime rejected t ## Remaining gates -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. +This is experimental. The throughput, maximum pause and memory targets set in [#372](https://github.com/openfl/libhxcpp/issues/372) are still open and tracked in [#446](https://github.com/openfl/libhxcpp/issues/446). 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. diff --git a/docs/IncrementalGc.md b/docs/IncrementalGc.md index 7ef286edc..6defaf002 100644 --- a/docs/IncrementalGc.md +++ b/docs/IncrementalGc.md @@ -1,8 +1,8 @@ # Incremental GC -Tracked in [#372](https://github.com/openfl/libhxcpp/issues/372). This is an experimental, opt-in collector for native C++ programs using Haxe 4.3 or later in the 4.x series. The existing collector stays the default. The concurrent prototype in [#327](https://github.com/openfl/libhxcpp/issues/327) is deferred in the separate `feature/concurrent-gc` worktree. +Developed in [#372](https://github.com/openfl/libhxcpp/issues/372). The performance gates still open are tracked in [#446](https://github.com/openfl/libhxcpp/issues/446). This is an experimental, opt-in collector for native C++ programs using Haxe 4.3 or later in the 4.x series. The existing collector stays the default. The concurrent prototype in [#327](https://github.com/openfl/libhxcpp/issues/327) is deferred in the separate `feature/concurrent-gc` worktree. -Incremental marking is implemented, including automatic pacing, scheduling hooks, write barriers, resumable containers, synchronous recovery and verification. It does not yet meet every performance gate in #372. A requested duration is a target, not a deadline: root capture, thread rendezvous, one object's native `__Mark`, weak closure, finalizers, reclamation and forced completion can run beyond it. Application frame timings remain the measure of interruption seen by a game. +Incremental marking is implemented, including automatic pacing, scheduling hooks, write barriers, resumable containers, synchronous recovery and verification. It does not yet meet every performance gate in #446. A requested duration is a target, not a deadline: root capture, thread rendezvous, one object's native `__Mark`, weak closure, finalizers, reclamation and forced completion can run beyond it. Application frame timings remain the measure of interruption seen by a game. ## Enable and use @@ -105,7 +105,7 @@ Counters include setup and explicit collections from process startup: These counters describe the collecting thread's successful invocations. They are not a distribution of every application thread's wait. Several assists can occur in one allocation burst, and explicit APIs can finish synchronously. Measure frame or request latency as well. The benchmark executable includes `incrementalGc` counters in its JSON when built with the flag. -Development measurements must compare the same workload, source, toolchain and hardware against the existing libhxcpp collector, with verification and test controls omitted. Record checksums, frame or request distributions, throughput, RSS and reserved memory. On the development machine `gc_frames` runs 10 to 16% slower than the existing collector and `gc_pauses` 5 to 9%, with the slowest 0.1% of work units under 1 ms against 5 to 8 ms, and up to 10% more peak memory. The harness's full collection between samples resets the existing collector's periodic full reclaim, so it hides that stop: compare with those collections removed as well. Do not treat either result as a universal speedup or a hard pause guarantee. The p99.9, maximum interruption, throughput and memory gates in #372 remain the acceptance criteria for promoting this mode beyond experimental use. +Development measurements must compare the same workload, source, toolchain and hardware against the existing libhxcpp collector, with verification and test controls omitted. Record checksums, frame or request distributions, throughput, RSS and reserved memory. On the development machine `gc_frames` runs 10 to 16% slower than the existing collector and `gc_pauses` 5 to 9%, with the slowest 0.1% of work units under 1 ms against 5 to 8 ms, and up to 10% more peak memory. The harness's full collection between samples resets the existing collector's periodic full reclaim, so it hides that stop: compare with those collections removed as well. Do not treat either result as a universal speedup or a hard pause guarantee. The p99.9, maximum interruption, throughput and memory gates set in #372, now tracked in #446, remain the acceptance criteria for promoting this mode beyond experimental use. ## Supported configurations