8000 Tags · savini98/jaseci · GitHub
[go: up one dir, main page]

Skip to content

Tags

Tags

dev

Toggle dev's commit message

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
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>
0