[javimosch]

Closes #667.

A map made while a scoped or goroutine arena is current is allocated from that arena and dies with it. A map made on the main goroutine's arena is malloc-backed instead — a long-lived map has to survive arena_reset(), and nothing at make() distinguishes it from a transient one — so it lives until the process exits and arena_reset() does not touch it.

That is right for the long-lived caches the malloc path exists for. It bites exactly one shape: a single-actor server whose request loop runs on main because its engine is not goroutine-safe, so it can neither hand each connection to a goroutine nor wrap the loop body in arena { } (the engine writes to globals and ARENA001 correctly refuses the escape).

map_free(m) hands that memory back — entries, their keys and values, the bucket array, the struct. On a map the arena owns it is a deliberate no-op rather than an error: the caller usually cannot tell which path make() took, and a silently-correct no-op beats a footgun that only fires in the configuration nobody tested.

Measured

	peak RSS
floor (empty program)	9,856 kB
200k maps, no map_free	104,320 kB — 94 MB of growth
200k maps, with map_free	11,392 kB — 1.5 MB of growth

Clean under AddressSanitizer on both the main-arena and arena-owned paths. Non-map arguments and wrong arity are refused at compile time.

Real consumer: microexits' per-request headers map comes from machweb's parse_headers on the main goroutine. Freeing it took that service from 1.5 kB/request to 0.07.

On the test

It compares peak RSS of the same workload built twice, with and without the call, minus a measured floor. Two earlier versions of this test were wrong in ways worth recording:

• the first read /proc/self/status from MFL and compared 0 against 0, because read_file returns empty on procfs (now read_file returns empty for /proc and /sys files (st_size is 0 there) #668) — it passed with map_free entirely stubbed out;
• the second compared totals rather than work, and ru_maxrss for a child includes what it inherited at fork, so it passed alone and failed inside the suite where the parent's RSS had grown.

The current one is verified to fail when the implementation is stubbed.

Full suite green: ok machin 458.005s.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XJdASnjD4R5h6xX2fzfMfk

Summary by CodeRabbit

• New Features

  • Added a map_free builtin to release memory used by temporary maps that are no longer needed.

• Documentation

  • Updated the guide to explain when map_free should be used and added a related memory note.

• Tests

  • Added coverage for freeing temporary maps, ensuring arena-managed maps are left alone, and validating argument checks.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: d8b78c24-0635-47f6-aec4-73343170b518

📥 Commits

Reviewing files that changed from the base of the PR and between c8b21ce and ca81caf.

📒 Files selected for processing (5)

• codegen.go
• guide.go
• map_free_test.go
• selfhost/cgprelude.src
• types.go

 _______________________
< Hasta la vista, bugs. >
 -----------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}