Title: Revisit M-table binding storage: per-function caching and budget-aware chunk locals · Issue #174 · purescript-lua/purescript-lua · GitHub
Open Graph Title: Revisit M-table binding storage: per-function caching and budget-aware chunk locals · Issue #174 · purescript-lua/purescript-lua
X Title: Revisit M-table binding storage: per-function caching and budget-aware chunk locals · Issue #174 · purescript-lua/purescript-lua
Description: Problem Every top-level binding lives in the M table, so every inter-binding reference is a hash lookup: the linked Data.Array output has 681 M.* references across 124 bindings. Measured: reading M.field in a loop is 2.4x slower than a l...
Open Graph Description: Problem Every top-level binding lives in the M table, so every inter-binding reference is a hash lookup: the linked Data.Array output has 681 M.* references across 124 bindings. Measured: reading M...
X Description: Problem Every top-level binding lives in the M table, so every inter-binding reference is a hash lookup: the linked Data.Array output has 681 M.* references across 124 bindings. Measured: reading M...
Opengraph URL: https://github.com/purescript-lua/purescript-lua/issues/174
X: @github
Domain: github.com
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Revisit M-table binding storage: per-function caching and budget-aware chunk locals","articleBody":"## Problem\n\nEvery top-level binding lives in the `M` table, so every inter-binding reference is a hash lookup: the linked `Data.Array` output has 681 `M.*` references across 124 bindings. Measured: reading `M.field` in a loop is 2.4x slower than a local under PUC Lua 5.1; in a LuaJIT trace it is a guarded load where a local is a register.\n\nHistory (the constraint that shaped the current design): early codegen emitted top-level bindings as chunk locals and real programs hit Lua 5.1 limits — 200 locals per chunk, and the 60-upvalue limit amplified by 5.1's pass-through accumulation, where a nested function reading an outer local costs an upvalue slot in every intermediate function (#19). The `M` table was the fix: unbounded fields, and `M` itself is the single upvalue everywhere. Any revisit must handle the limits by construction, not assume programs stay small.\n\n## Approach\n\nBudget-aware emission with `M` as the overflow valve (the design principle). Every budget overflow degrades the specific reference or binding back to today's `M` form, so the worst case is exactly the current output and the limits stop being correctness cliffs.\n\n### Stage 1: per-function caching of M fields (limit-proof by construction)\n\nStorage untouched: `M` remains the single source of truth and the single upvalue, so neither limit can be approached. A `Lua.Optimizer` pass caches `M.x` fields used two or more times in a generated function body into locals at function entry (capped at ~30 per function, prioritized by use count):\n\n```lua\nM.Data_Array_span = function(p)\n return function(arr)\n local index, add = M.Data_Array_index, M.Data_Array_add\n local go\n go = function(i)\n local v = index(arr)(i)\n -- ...\n end\n```\n\nSemantics: the read moves to function entry — by the time any generated function is called, module init has assigned the bindings it reads, and `M` is not mutated within a call; the runtime-lazy scheme is unaffected. This is the classic \"localize globals\" optimization from LuaJIT guides.\n\n### Stage 2: two-tier storage with budget accounting\n\nTop-K bindings by static reference count are emitted as real chunk locals; the tail stays in `M`; exported bindings are mirrored into the export surface. Two budgets are computed over the finished Lua AST before printing:\n\n1. Locals: a chunk-local counter with a ceiling of ~180 (200 minus fixture locals and headroom). Overflow keeps the binding in `M`.\n2. Upvalues: the killer of the old design. Accounting runs bottom-up over the function tree: `upvals(f) = |own outer-local references ∪ children's pass-through demands|`. When a function proto would exceed ~55, individual references are demoted — printed as `M.x` — while the binding stays a local for everyone else.\n\nA program that fits the budgets (like `Data.Array` with 124 bindings) loses the `M` table entirely: pure locals, with the module export table referencing them directly. `K` for larger programs is chosen from #172 measurements.\n\n### Rejected alternatives\n\nPer-module closure scopes wired by upvalues — the road that led to #19; transitive pass-through accumulation makes the explosion structural. Globals/`setfenv` — `GETGLOBAL` in 5.1 is the same hash lookup, on `_G`. Integer-indexed storage (`B[42]`) — still a guarded load in traces, and unreadable output.\n\n### ADR\n\nThis changes the codegen structure, so the decision gets an ADR — `docs/adr/0001-top-level-binding-storage.md`, the first in the repo, establishing the practice. It records the full history (locals, then `M`, then two-tier), the budget model, and the rejected alternatives above.\n\n## Prerequisites / Relations\n\nIndependent in the dependency graph — pure codegen, no hard prerequisite. It builds on the #19 history above (the constraint the design must respect). The `K` threshold for large programs is chosen from #172's measurements, and #172's `M.field`-vs-local microbenchmark is the tool that scores the win. The multiplier grows once uncurrying (#24) and loopification (#181) land: real loops then exist and a cached local becomes a loop-hoisted register in a LuaJIT trace.\n\n## Verification / Measurement\n\nModest immediately: 2.4x on multi-use function bodies and module init (the #172 `M.field`-vs-local microbenchmark plus macro timings). The headline structural observable: a program that fits the budgets — `Data.Array`, 124 bindings — emits no `M` table at all, only chunk locals with the export table referencing them directly. Structural goldens churn mechanically (`PSLUA_GOLDEN_ACCEPT` + diff review); as a pure-codegen change, eval goldens must not move.\n","author":{"url":"https://github.com/Unisay","@type":"Person","name":"Unisay"},"datePublished":"2026-07-06T09:40:26Z","url":"https://github.com/purescript-lua/purescript-lua/issues/174"}
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format) |
| route-controller | voltron_issues_fragments |
| route-action | issue_layout |
| fetch-nonce | v2:d3364399-306a-0c15-4d2a-5a3cf42b296a |
| current-catalog-service-hash | 81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114 |
| request-id | BD86:272DC0:663350:840312:6B00DFBA |
| html-safe-nonce | 3cd9e3a4f1f54610a994bfc31b91005669bdb7a1dbe3a1de9ed456860ee6a487 |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCRDg2OjI3MkRDMDo2NjMzNTA6ODQwMzEyOjZCMDBERkJBIiwidmlzaXRvcl9pZCI6Ijc1NzgxNTM5OTk1MjY4NDYzOTQiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ== |
| visitor-hmac | af9c5957f1bbb0c5e8a9a7c2a54d7405beb36c4953b95c913363cb6c9d829c64 |
| hovercard-subject-tag | issue:4817872772 |
| github-keyboard-shortcuts | repository,issues,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/purescript-lua/purescript-lua/174/issue_layout |
| twitter:image | https://opengraph.githubassets.com/8f3530cc85238d41c2479888fb213194d817e522e9b1bfb071d9704ff3388311/purescript-lua/purescript-lua/issues/174 |
| twitter:card | summary_large_image |
| og:image | https://opengraph.githubassets.com/8f3530cc85238d41c2479888fb213194d817e522e9b1bfb071d9704ff3388311/purescript-lua/purescript-lua/issues/174 |
| og:image:alt | Problem Every top-level binding lives in the M table, so every inter-binding reference is a hash lookup: the linked Data.Array output has 681 M.* references across 124 bindings. Measured: reading M... |
| og:image:width | 1200 |
| og:image:height | 600 |
| og:site_name | GitHub |
| og:type | object |
| og:author:username | Unisay |
| hostname | github.com |
| expected-hostname | github.com |
| None | 043c3f30fbcbe2c6c8e729e10cbbbc90c406546f9fbbb67c648d38f6b7d16daf |
| turbo-cache-control | no-preview |
| go-import | github.com/purescript-lua/purescript-lua git https://github.com/purescript-lua/purescript-lua.git |
| octolytics-dimension-user_id | 131581790 |
| octolytics-dimension-user_login | purescript-lua |
| octolytics-dimension-repository_id | 587200487 |
| octolytics-dimension-repository_nwo | purescript-lua/purescript-lua |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 587200487 |
| octolytics-dimension-repository_network_root_nwo | purescript-lua/purescript-lua |
| turbo-body-classes | logged-out env-production page-responsive |
| disable-turbo | false |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 5425dc24e8bd8d6fca9641a12afc984825a43875 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
| react-app-name | issues |
Links:
Viewport: width=device-width