Conversation
…ment.md
The phrase "cooperative reference-counting overlay" was project-internal
vocabulary with no presence in the GC literature. Renamed to "selective
reference-counting overlay" throughout — "selective" accurately captures
the design's defining property (refcount tracking is opt-in per object
class, only for those needing DESTROY / weaken semantics) and is
descriptive in standard GC terminology.
Project-wide rename (~86 occurrences across 32 files):
- All user-facing docs (docs/, AGENTS.md, jperl scripts)
- All dev/ design and module notes
- Source comments in src/main/java/.../runtimetypes/* and operators/*
- B.pm and Class/MOP/Method/Accessor.pm Perl modules
- Skipped: bundled CPAN/Perl docs (perlthrtut.pod, Moose cookbook),
TLD list (PublicSuffix.pm "KPMG International Cooperative"),
build/target/cpan_build_dir, "cooperatively" (different word).
New docs/reference/memory-management.md:
- User-facing summary of the selective refcount overlay (no project
history — that lives in dev/architecture/weaken-destroy.md and
dev/modules/moose_support.md).
- "How the overlay works" mechanism table.
- "Where this fits in the GC literature" section with verified links:
- The Garbage Collection Handbook (Jones, Hosking, Moss)
- Bacon, Cheng, Rajan 2004 "A Unified Theory of Garbage Collection"
- Blackburn & McKinley 2003 "Ulterior Reference Counting"
- Wikipedia: Reference counting / Tracing GC / Garbage collection /
Finalizer
- Java java.lang.ref package summary (JDK 21)
- perldoc.perl.org perlobj#Destructors
- Explains why "selective" rather than "deferred" or "ulterior" — the
partition criterion is per-class behavioural (does this need
finalization?), not generational or write-barrier-based.
- Comparison table: Perl 5 vs JVM finalization vs PerlOnJava.
docs/reference/architecture.md:
- Replaced inline 14-line DESTROY section with a 4-line pointer to
the new memory-management.md.
- Added memory-management.md to "Related Documentation" list.
dev/architecture/weaken-destroy.md (separate prior work in this branch):
- Updated to reflect property-based walker gate (D-W6.18) replacing
the class-name heuristic (Class::MOP/Moose/Moo allowlist).
- Documented MortalList.flush()'s narrow auto-trigger
(storedInPackageGlobal + hasWeakRefsTo) and its per-flush
reachable-set cache.
- Added section 10b on RuntimeBase.activeOwners /
reachableOwnerCount infrastructure (D-W6.14 / D-W6.16).
- Documented PJ_REFCOUNT_TRACE / PJ_WEAKCLEAR_TRACE / PJ_DESTROY_TRACE.
Verification:
- `make` passes (build + all unit tests).
- `make check-links` passes (267/267 internal links OK).
- All 8 external literature URLs verified with curl (HTTP 200 / valid
302 redirects to ACM for DOIs).
Generated with [Devin](https://cli.devin.ai/docs)
Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com>
fglock
force-pushed
the
docs/selective-refcount-and-memory-management
branch
from
46274a4 to
220a157
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
DESTROY/weakensemantics).docs/reference/memory-management.md— user-facing summary of the selective refcount overlay, with verified links to the GC literature (Bacon 2004, Blackburn & McKinley 2003, The Garbage Collection Handbook, Wikipedia, JDKjava.lang.ref,perlobj).docs/reference/architecture.mdwith a brief pointer to the new doc.dev/architecture/weaken-destroy.mdto reflect the property-based walker gate (D-W6.18) andactiveOwners/reachableOwnerCountinfrastructure that landed in PR fix: replace class-name walker-gate heuristic with property-based gate #618.Why "selective" instead of "cooperative"
The new doc has a "Where this fits in the GC literature" section that explains the choice. In the Bacon/Cheng/Rajan framing, hybrid collectors partition the heap and apply tracing to one part and reference counting to the other; PerlOnJava picks the partition along a per-class behavioural boundary (does this class need finalization or weak-ref semantics that the JVM cannot already provide?). That's "selective" — not "deferred" (a write-barrier optimisation) and not "ulterior" (a generational boundary).
Scope of the rename
86 occurrences across 32 files:
docs/,AGENTS.md,jperlscripts)dev/design notes and module-level docssrc/main/java/.../runtimetypes/*.javaandoperators/*.javaB.pmandClass/MOP/Method/Accessor.pmSkipped:
perlthrtut.pod, Moose cookbook — different sense of "cooperative")PublicSuffix.pm("KPMG International Cooperative" company name)build/,target/,cpan_build_dir/Test plan
make(full build + all unit tests) passesmake check-links(lychee --offline) — 267 OK, 0 errorscurl(HTTP 200 or valid 302 redirect)cooperativematches remain in any code or doc that should have been renamed (rg -i '\bcooperative\b'shows only the intentionally-skipped files)Generated with Devin