Skip to content

perf(ffi): one allocation for a Go object and its handle, and no arena in a Dart close - #828

Merged
kixelated merged 3 commits into
mainfrom
quest/m1/ffi-speed/object-ownership
Nov 15, 2026
Merged

kixelated merged 3 commits into
mainfrom
quest/m1/ffi-speed/object-ownership

Conversation

@kixelated

@kixelated kixelated commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Profiles Go's and Dart's object return, takes the two cuts that don't change when an object is freed, and rewrites object-ownership to the work left: the nursery the maintainer chose.

What the profile shows. Each runtime spends most of an object return registering the object with its collector. The binding can't cut that cost without changing when a dropped object is freed.

  • Go (perf, track.Info() returned and closed): runtime.AddCleanup plus the Cleanup.Stop that Close makes take 39%. The three cgo crossings (the call, the value's drop, the handle's free) take a third. The collector's own threads take a tenth.
  • Dart: Dart_NewFinalizableHandle, its crossing, and its finalization by the collector cost 1,600 instructions per object, three quarters of a return and close. A variant without them took 62 to 65 ns, against 176 to 245.

What changes

  • Go: own_<c> and lend_<c> allocate the object and its rt.Handle_ together, in one anonymous struct. Each call that holds the handle now keeps the object reachable, so a collected object has no holds. The cleanup therefore frees the raw handle directly (free_<c>(raw)), and Handle_.Collected is gone. rt.NewHandle_ becomes (*Handle_).Init. That costs 70 fewer instructions and one fewer allocation per object.
  • Dart: a checked object's _drop() no longer builds and ends an _Arena it never used. That costs 136 fewer instructions per close.
  • just ffi bench-build: a rerun failed with mv: ... are the same file. Cargo hardlinks target/release/libmoq.so to its build of the same features, which the last run had moved to python/. The recipe now removes the stale copy first.
  • Quests:
    • object-ownership.md becomes the nursery that would skip the registration for objects closed early. It records the measured alternatives it rejects and the maintainer's decision to build it.
    • ready-await.md no longer requires it. It profiles the await with ownership's share set apart, using the split in the bench README, rather than waiting on that decision.
  • Docs: item 2 of bench/ffi/README.md's "What a call spends" now gives the split. It no longer says Dart uses a NativeFinalizer; that changed in perf(ffi): cheaper Dart futures ready at their first poll, and cheaper object handles #486.

Public API

No generated API changes. The generated object types keep Handle_ *rt.Handle_, so copying one copies only a pointer, as before. The runtime package's NewHandle_ and Handle_.Collected are replaced by Handle_.Init. That package documents all three as "for the generated packages: use none of it". Wire: none.

Validation

  • just ci passes. This includes api_go, whose owned check waits for "the GC frees what nobody closed", and which now passes through the direct-free cleanup. api_dart and go_module pass too.

  • Instruction counts (perf stat -e instructions:u) of an object-only program built against the export before and after, three runs each, on nixos (Ryzen 9 5900XT):

    before after per object
    Go (5.5M returns plus 5M calls) 21.53 to 21.54 G 21.15 to 21.16 G −70
    Dart (15M returns plus 15M calls) 48.73 to 48.75 G 46.69 G −136

    Go's user cycles fell 2.5 to 3% over the whole program.

  • The full bench programs, before and after, in turn for five rounds at a load of 5.6 to 26 (median CPU ns):

    case Go before Go after Dart before Dart after
    object return 293 297 213 188
    stamped write 351 336 362 385

    Go's 70 instructions are within this load's noise. The stamped write returns no object since feat(ffi)!: Copy types cross by value #742 made Timestamp cross by value, so it moved by noise alone.

  • Measured and rejected:

    • Dart's NativeFinalizer.attach without detach: 770 to 1,070 ns per return.
    • Go's runtime.SetFinalizer: 13% fewer instructions than AddCleanup plus Stop in a microbenchmark. But it runs every free on one goroutine and keeps each object for one more collection.
    • Leaving Go's cleanup registered at Close: 290 to 450 ns per object against 120 for Stop, in a microbenchmark.

Decisions

Settled by the maintainer (2026-11-15, comment), recorded in the quest's Plan; not implemented here:

  • ✅ object-ownership continues with a nursery: Go and Dart keep the last 64 returned objects and register one with the collector only if it leaves the nursery still open (rejected: keep per-object registration and delete the quest; flush on each event-loop turn).

Choices made without asking, for review:

  • I rewrote the quest rather than deleting it. Its Goal (close to C) isn't met, and what remains is the nursery, which waits on a decision that only the maintainer can make.
  • I dropped ready-await.md's Required on this quest. Otherwise it would stay blocked on that decision, and the bench README now gives ownership's share for it to set apart.
  • I considered and skipped a single cgo crossing for a checked Go Close (drop and free together). It either reports a spurious ErrClosed to a call racing a Close that then fails, or reads Go's atomic state from C. It also overlaps shared-borrow's rewrite of the state word.
  • I considered and skipped folding Dart's _own crossing into the returning call's glue: about 24 ns, direct returns only. The nursery would remove that crossing for objects closed early anyway.

Follow-ups

None new. The rewritten object-ownership holds the nursery, now settled.

Caused by

  • kixel-ai/rust2#407 - moved the Python build's library with mv, which refuses on a rerun when cargo has hardlinked the same file to both paths (found by person: this run)

Models

Size: M
Implementer: Claude, claude-opus-5-5, unknown effort (arm B)
Implementer: Claude Code, claude-opus-5-5, low effort (iterate, XS, arm B)

🤖 Generated with Claude Code

(Written by Claude Opus 5.5 with low effort)

Review

Rewritten by quest review after each round.

  • Head: f291b8f

  • Base: origin/main at 4099730

  • Risk: medium, the base has no RISK.md to name what is always high or customer-facing, so every change is medium

  • Classified: medium by default

  • Reviewer: Codex, gpt-6.1-sol, high effort

  • Session: 01a1de16-0427-7610-8889-468eb6a401f4, round 2

  • Score: 9/10, The incremental change only records the nursery decision in documentation and introduces no findings; the previously reviewed ownership changes remain unverified by builds or tests.

  • Rounds: 2; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

  • Reviewer: Codex, gpt-6.1-sol, medium effort, shadow

  • Session: 01a1dea9-4f07-7fb0-a930-8b724c4bf5f6, round 1

  • Score: 9/10, The ownership changes appear consistent with existing lifetime handling and have no actionable findings, though builds and tests were not run as instructed.

  • Rounds: 1; first round 0; findings 0: fixed 0, refuted 0, open 0

  • Findings: none

Summary by CodeRabbit

  • Performance Improvements
    • Reduced overhead when returning and closing objects in Go and Dart.
    • Go object handling now uses fewer allocations, while Dart object closing avoids temporary cleanup work.
  • Documentation
    • Updated FFI ownership benchmarks with profiling details and timings for Go, Dart, and Kotlin.
    • Revised ownership and ready-read benchmark notes to clarify how object ownership affects measured performance.

Summary by CodeRabbit

  • Performance
    • Reduced overhead when returning and closing FFI objects in Go and Dart.
    • Go object and handle setup now uses a single allocation.
    • Dart object cleanup no longer creates a temporary arena.
  • Documentation
    • Updated ownership cost measurements and benchmark guidance for Go, Dart, and Kotlin.
    • Added details on the planned handling of recently returned objects and links to shared-borrow documentation.

@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

Go object conversion now allocates each object and handle together, and Dart generated drop methods no longer create a temporary arena. Ownership documentation adds profiling results and a nursery proposal. The Python export command removes the destination library before moving the new build output.

Changes: FFI object ownership

Layer / File(s) Summary
Go and Dart ownership handling
ffi/runtime/rt.go, ffi/src/go.rs, ffi/src/dart.rs
Go initializes handles in place and allocates objects with their handles. Owned objects register cleanup to free the C handle; lent objects use no free callback. The generated Dart drop method calls the Rust drop function without a temporary arena.
Ownership measurements and proposals
bench/ffi/README.md, quest/m1/ffi-speed/object-ownership.md, quest/m1/ffi-speed/ready-await.md
The README adds Go and Dart profiling costs and timings. The ownership quest describes a 64-object nursery proposal and alternatives. The ready-await quest separates returned-frame ownership from ready-path profiling.

Python library export

Layer / File(s) Summary
Python library replacement
ffi/justfile
The export command removes the existing Python library destination before moving the newly built library into place.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Refactor

Merge Risk: Minimal · up to f291b

This change reduces allocation overhead for Go objects and removes an unused arena from Dart object close. It also makes repeated export builds reliable. No concrete defect was found, so it looks safe to merge.

Security architecture risk: Minimal · up to a4d8f

The inspected changes preserve the existing ownership controls and do not establish an introduced security or failure-containment risk. Go co-allocation keeps handles reachable during active calls, and Dart retains native status checking after removing the unused arena.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The ownership change applies across objects emitted by the Go generator, making native-memory lifetime the principal security-sensitive scope. A failure of the reachability invariant could affect the consuming process; the inspected change does not establish an additional tenant, service, credential, or privilege boundary.

Trust Boundaries and Controls

  • observed — The changed paths continue to operate on native handles supplied through existing binding conversions. Go retains atomic hold and closed-state checks. Dart retains the served-call status isolation mechanism, which copies a call-local status into the isolate's shared cell only after serving completes.

Resilience and Maintainability Implications

  • inferred — The strongest premature-free and duplicate-free counterexamples are constrained by co-allocation reachability, owner retention during calls, cleanup cancellation before explicit freeing, and atomic abandonment. The inspected base-to-head transition does not establish weakened ownership or failure-containment guarantees.
Pre-merge checks: Passed 4

Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title names two concrete changes that the changeset implements. The Go change puts a Go object and its Handle_ in one allocation (go.rs, rt.go Init replacing NewHandle_). The Dart change removes t…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names two concrete changes that the changeset implements. The Go change puts a Go object and its Handle_ in one allocation (go.rs, rt.go Init replacing NewHandle_). The Dart change removes the temporary _Arena from the close path (dart.rs _drop override). The title matches the main code change. The quest and benchmark documentation edits are not in the title, which is expected for a title. The title is one short sentence and meets the length and clarity principles, though 17 words is on the long side.

Finishing Touches

Generate unit tests (beta)

  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: ab8560e6-194e-4844-aa31-6a326d302b63
Commits

Reviewing files that changed from the base of the PR and between a4d8f5f and f291b8f.

Files selected for processing: 1

  • quest/m1/ffi-speed/object-ownership.md
Files skipped from review as they are similar to previous changes: 1

  • quest/m1/ffi-speed/object-ownership.md

Limit details: You’ve used all 10 included reviews currently available.

…a in a Dart close

Profile Go's and Dart's object return: most of it is each runtime's per-object
registration with its collector. Allocate a Go object with its handle, whose
cleanup then frees the raw handle directly, and drop the `_Arena` a Dart
checked close made for nothing. Rewrite the quest to the nursery that would
skip the registration, pending a maintainer decision, and unblock ready-await.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated kixelated changed the title Cheaper returned-object ownership in Go and Dart perf(ffi): one allocation for a Go object and its handle, and no arena in a Dart close Nov 15, 2026
@kixelated
kixelated marked this pull request as ready for review November 15, 2026 07:24
pullfrog[bot]
pullfrog Bot previously approved these changes Nov 15, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

This review covers the Go handle allocation and cleanup rewrite, the Dart _drop() change, the bench-build rerun fix, and the doc and quest rewrites.

  • One allocation per Go object: own_<c>/lend_<c> allocate the object and its rt.Handle_ together, and own_'s runtime.AddCleanup now frees the raw handle directly. This is sound:
    • Every hold keeps &o.h reachable, through the deferred unhold_(h, o) and arena_.held. That pointer is interior to o, so the cleanup cannot run while a call holds the handle.
    • Every closing path calls Cleanup.Stop() while the object is still reachable: unchecked Close, checked Close through Moved, and a move into Rust. So the unconditional free_<c>(raw) cannot double-free.
    • lend_ registers no cleanup.
    • A copy of the object (x := *obj) now also keeps the cleanup from running. Before, the cleanup on obj could free the handle while x was still in use.
  • Handle_.Init replaces NewHandle_, and Collected is gone: nothing else in the repo references either name, and TAKEN drops NewHandle_ to match.
  • Checked Dart _drop() without _Arena: the arena was never used. _n.status is the isolate's own persistent pointer, and a nested call takes its own stack mark either way.
  • moq-export rerun: rm -f "$out/python/$lib" before the mv avoids GNU mv's "are the same file" error when cargo has hardlinked both paths.
  • Docs and quests: bench/ffi/README.md item 2 now gives the profile split and no longer mentions NativeFinalizer. object-ownership.md becomes the nursery plan with a Maintainer: decision under ## Waiting, and ready-await.md no longer requires it.

Pullfrog  | View workflow run | Using claude-opus-5-5 | 𝕏

@kixelated

Copy link
Copy Markdown
Collaborator Author

Maintainer decision (2026-11-15, via /quest-run):

  • ✅ /quest-merge pick (rejected: skip, /quest-delete).
  • ✅ object-ownership continues with a nursery: Go and Dart keep the last 64 returned objects and register one with the collector only if it leaves the nursery still open (rejected: keep per-object registration and delete the quest; flush on each event-loop turn).

(Written by Claude Opus 5.5 with high effort)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated

Copy link
Copy Markdown
Collaborator Author

The maintainer decision is recorded on head f291b8f: quest/m1/ffi-speed/object-ownership.md's Plan now settles the nursery (last 64 returned objects, registered with the collector only on leaving it still open), lists the rejected options, and drops its ## Waiting. The nursery itself is not implemented here; the quest holds it.

(Written by Claude Opus 5.5 with low effort)

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ No new issues found.

Reviewed changes

This review covers the one commit since the prior Pullfrog review.

  • Recorded the nursery decision: quest/m1/ffi-speed/object-ownership.md now states the nursery is settled by the maintainer. It moves the accepted later free and the rejected alternatives into the Plan, and drops the ## Waiting section. The change is docs only.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@kixelated
kixelated added this pull request to the merge queue Nov 15, 2026
Merged via the queue into main with commit f84ec06 Nov 15, 2026
8 checks passed
@kixelated
kixelated deleted the quest/m1/ffi-speed/object-ownership branch November 15, 2026 10:51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant