Repository navigation
Tags
Tags
docs(native): describe the tuple-bind ownership rule that actually ho… …lds (jaseci-labs#8019) Follow-up to jaseci-labs#8004, which merged while this documentation commit was still in review. jaseci-labs#8004 deleted the `retain_fields = not is_value` rule and gave heap tuple boxes a destructor that releases their fields, but three descriptions of the old rule survived in jaseci-labs#7982's fixture and tests. Their assertions kept passing, so nothing went red; the prose was simply false. ## What was wrong ``` jac/tests/compiler/passes/native/fixtures/rc_tuple_unpack_optional.jac:6 on `retain_fields` (false for a value tuple) and on the target alloca jac/tests/compiler/passes/native/fixtures/rc_tuple_unpack_optional.jac:19 pre-existing `retain_fields = not is_value` rule for value tuples jac/tests/compiler/passes/native/test_native_rc_ownership.jac:231 # old-value release (`retain_fields = not is_value`), which predates ``` The fixture docstring also asserted that "releasing a tuple box does not decrement its fields" and that the optional unpack "takes neither the retain nor the old-release". Both were true before jaseci-labs#8004 and are false after it. The second test's comment claimed both shapes "currently drop 2 rather than 4"; they now drop 4. ## What they say now The rule in force: a heap tuple box owns one reference per managed field and its destructor releases them; the unpack retains by provenance (a field loaded out of a box is always borrowed from the box's own reference, a value-tuple element is borrowed unless recorded owned); and the target slot's previous contents are released for both tuple representations, reached through the optional payload when the slot is an optional rather than a raw pointer. ## The assertion message `"tuple unpack into an optional slot destroys each object exactly once"` still measures 2, but for a different reason than when it was written: previously no retain, no release, and a box that abandoned its fields; now a retain per bind, a destructor that drops the box's reference, and a release at scope exit. The count is unchanged, so the test passed for a reason its message no longer described. The message now names the count each failure mode actually produces, and that is measured rather than asserted. Removing the box destructor: ``` E AssertionError: 2 allocations must produce 2 drops, got 0 (0 means the box abandoned its fields, more than 2 that the bind skipped its retain and each payload was released twice) FAILED test_native_rc_ownership.jac::tuple unpack into an optional slot destroys each object exactly once 1 failed, 13 passed ``` The sibling test needed no rewording beyond its comment: it asserts `opt_drops == plain_drops` rather than a constant, which is exactly what let it survive both sides moving from 2 to 4. ## Scope Comments and docstrings only, no behavior change, no `jac/jaclang/` files (so no release-note fragment). ``` PYTEST_XDIST_AUTO_NUM_WORKERS=2 jac test \ jac/tests/compiler/passes/native/test_native_rc_ownership.jac \ jac/tests/compiler/test_compile_options.jac # 33 passed ``` Co-authored-by: marsninja <marsninja@users.noreply.github.com>