docs: align lifecycle KDoc with actual GC management#490
Merged
Conversation
Every handle-owning class except ZBytes is now GC-backstopped (Config joined in zenoh-flat-jni PR#8), and the docs now say exactly what happens to forgotten instances: - Session: close() KDoc contradicted the code — close undeclares every live declaration, it does not leave them alive; class KDoc notes the GC backstop. - ZBytes: new lifecycle section — created ZBytes are plain values; received ones free their native buffer on first read; a received payload/attachment that is never read keeps it (deliberately NOT GC-managed: per-message Cleaner cost measured -23% thr @8B). - Publisher/Querier: session reference is weak — forgotten instances are undeclared by the GC backstop, not at session close only. - Subscriber/Queryable: session reference is strong — dropping the reference does NOT stop them; active until undeclare or session close. - Scout/LivelinessToken: 'dropped' now spelled out as GC-collected, non-deterministic; close for prompt effect. - KeyExpr (declared) / Config: backstop notes. CI pin bumped to flat-jni dbb1f8c (Config gc_managed, PR#8). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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.
What
Aligns the SDK lifecycle KDoc with the actual GC management, following an audit of every
ptr_classagainstzenoh-flat-jni's.gc_managed()roster. With paired ZettaScaleLabs/zenoh-flat-jni#8 (Config joins), every handle-owning class except ZBytes is GC-backstopped when forgotten — and the docs now say exactly what happens to forgotten instances.Fixes found by the audit:
Session.close()KDoc contradicted the code: it claimed declarations bound to the session "will still be alive" after close, butclose()undeclares every strong and weak declaration. The doc now matches the behavior, and the class KDoc notes the GC backstop (explicitcloserecommended for deterministic release).ZBytesgets the lifecycle section it was missing — the one class where GC will not save the user: created ZBytes are plain values (no native memory); received ones free their native buffer automatically on first read; a received payload/attachment that is never read keeps its native buffer (deliberate hot-path exclusion: per-message Cleaner registration measured −23% throughput @8B).Publisher/Querier: the session reference is weak — a forgotten instance is undeclared by the GC backstop (the old text implied it waited for session close).Subscriber/Queryable: the session reference is strong — dropping your reference does not stop the subscription/queryable; it stays active untilundeclare/closeor session close (zenoh semantics).Scout/LivelinessToken: "automatically undeclared when dropped" now spelled out as GC-collected, non-deterministic;closefor prompt effect.KeyExpr(declared) andConfig: short backstop notes (declared keyexprs are strong session declarations; a Config is consumed byopen/scout, an unused one is GC-released).Doc-only on the Kotlin side; CI pin points at flat-jni#8's branch tip
dbb1f8c(bump to the merge commit after it lands).Tests
113 jvmTest, 0 failures (composite build against the pinned flat-jni).
🤖 Generated with Claude Code