Skip to content

feat: let a closure decide the order functions are emitted in - #342

Open
logan-gatlin wants to merge 3 commits into
mainfrom
order-functions-by-uses
Open

logan-gatlin wants to merge 3 commits into
mainfrom
order-functions-by-uses

Conversation

@logan-gatlin

@logan-gatlin logan-gatlin commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Makes the order defined functions are emitted in configurable, instead of changing the default, as discussed above.

ModuleConfig::function_order takes a closure that reorders the defined functions in place. Each one is a FunctionInfo with id(), size() and uses(), which is how many times the module writes its index. For example, to give the most-referenced functions one-byte indices:

config.function_order(|_module, functions| functions.sort_by_key(|f| Reverse(f.uses())));
  • The default stays largest first, and output is byte-identical to main. The docs say the default isn't guaranteed, so the tests don't lock it in.
  • FunctionInfo can't be built or cloned outside walrus, so the closure can only reorder the functions.
  • Use counts are only gathered when a closure is set. That costs about 8 ms on a 22 MB module.

New tests are in crates/tests/tests/function_order.rs.

@wasm-bindgen-bot wasm-bindgen-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ LGTM

@wasm-bindgen-bot wasm-bindgen-bot Bot added the merge-ready The bot's review of its own PR found no concerns; ready for a human approval label Nov 12, 2026
@logan-gatlin

Copy link
Copy Markdown
Contributor Author

I don't think function ordering effects performance for cloudflare workers because they don't do streaming instantiation. Order matters when a large module is being streamed to the client, and the client starts compiling / executing the module before its fully downloaded. In these cases I think most-used-first is still the right call. The functions likely to be executed first will arrive first.

@logan-gatlin
logan-gatlin force-pushed the order-functions-by-uses branch from ce98fc5 to 81f029f Compare November 12, 2026 21:28
@wasm-bindgen-bot wasm-bindgen-bot Bot added merge-ready The bot's review of its own PR found no concerns; ready for a human approval and removed merge-ready The bot's review of its own PR found no concerns; ready for a human approval labels Nov 12, 2026
@guybedford

Copy link
Copy Markdown
Contributor

I'm okay with reordering, but it would help to have a very clear framing for the benefit. Perhaps streaming instantiation would benefit from a call graph ordering of sorts instead? Are there any other benefits of using small numbers for common functions?

If we do land this, we should make a clear note that the tests are not there to lock this behaviour in, to leave future reorderings on the table.

@logan-gatlin

logan-gatlin commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor Author

Yeah most-used-first is pretty much just a cruder version of call-graph ordering, and I'd bet the latter is actually faster if the difference is measurable at all. I'm leaning towards making function order configurable instead. My tool wants most-used-first just for the size reduction, but other users may want something different.

Will do some benchmarks and file a new PR or update this one

@logan-gatlin logan-gatlin added do not land PR should not be merged and removed merge-ready The bot's review of its own PR found no concerns; ready for a human approval labels Nov 12, 2026
@logan-gatlin
logan-gatlin force-pushed the order-functions-by-uses branch from 81f029f to ba6d385 Compare November 13, 2026 18:41

@wasm-bindgen-bot wasm-bindgen-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Since my last review the PR was only rebased; the changelog entry now sits next to the base branch's new entries, and the code and tests are unchanged, so I still have no code concerns. What's new is the discussion: @​guybedford (core) asked that, if this lands, it say clearly that the tests do not lock in this order, so it can be reordered later. Nothing in the PR says that yet. @​logan-gatlin has also said they lean towards making function order configurable and may update this PR or open a new one, so the design isn't final. On the question "are there any other benefits of using small numbers for common functions?": as far as I can tell the only benefit is encoded size, since every call/return_call/ref.func, export, element entry and start index that drops below 128 saves a byte, and I know of no engine that treats low function indices differently.

Not merge-ready:

  • The core member's request for a note that the tests do not lock in this function order hasn't been addressed.
  • The author has said they may rework this into a configurable ordering, so the design isn't settled yet.

walrus emits defined functions, and so numbers them, largest first. That
suits engines that compile functions in parallel, but a size optimizer
wants the most-referenced functions first, so that their indices take one
LEB128 byte, and streaming instantiation may want call-graph order.

`ModuleConfig::function_order` takes a closure that is given every
defined function as a `FunctionInfo` (its id, size and how many times
its index is written), in the default order, to reorder in place.
`FunctionInfo` can't be built, cloned or replaced outside walrus, so the
closure can only permute the functions. Walrus calls it once per emit,
and both the function and the code section use the order it leaves.

The default order is unchanged, and documented as not guaranteed. Use
counts are only gathered when a closure is set.
@logan-gatlin
logan-gatlin force-pushed the order-functions-by-uses branch from ba6d385 to 66752ef Compare November 16, 2026 08:37
@logan-gatlin logan-gatlin changed the title perf: number functions most-referenced first feat: let a closure decide the order functions are emitted in Nov 16, 2026
@logan-gatlin logan-gatlin removed the do not land PR should not be merged label Nov 16, 2026
@wasm-bindgen-bot wasm-bindgen-bot Bot added the merge-ready The bot's review of its own PR found no concerns; ready for a human approval label Nov 16, 2026
Rather than collecting every called function id into each function's
EmitFacts and merging them afterwards, the parallel body walks increment
one AtomicU64 per function arena slot. The table is only allocated when a
function_order closure is set.
@wasm-bindgen-bot wasm-bindgen-bot Bot removed the merge-ready The bot's review of its own PR found no concerns; ready for a human approval label Nov 18, 2026

@wasm-bindgen-bot wasm-bindgen-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Since my last review the PR changed design. The default order (largest first) is no longer changed. Instead, ModuleConfig::function_order takes a closure that reorders FunctionInfo { id, size, uses } in place, and c8106f1 counts code uses in a shared table of AtomicU64s, as @​guybedford suggested in his thread. That thread is his to resolve. My earlier concern about locking in the default order is fixed: the docs, changelog and function_order.rs now say the default isn't guaranteed. The design and tests look solid. One problem remains: uses() never counts ref.func in table initializer expressions, even though those indices are emitted.

Not merge-ready:

  • FunctionInfo::uses never counts ref.func in table initializer expressions, even though they are emitted, so documented counts are wrong for those functions.

Comment thread src/module/functions/mod.rs Resolved
ModuleTables::emit writes a table's init expression, so a ref.func there
writes a function index, but FunctionInfo::uses didn't count it.
@wasm-bindgen-bot wasm-bindgen-bot Bot added the merge-ready The bot's review of its own PR found no concerns; ready for a human approval label Nov 18, 2026

@guybedford guybedford left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The atomics change and the table initializer fix both look good. Just a couple of small comment nits; this needs a rebase onto main before landing.

Comment on lines +708 to +711
/// How many times the emitted module writes this function's index: in
/// `call`, `return_call` and `ref.func` instructions, exports, element
/// segments, global and table initializers and the start section. The name section
/// and DWARF aren't counted.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This line is now past the wrap width, and custom sections in general aren't counted, not just these two:

Suggested change
/// How many times the emitted module writes this function's index: in
/// `call`, `return_call` and `ref.func` instructions, exports, element
/// segments, global and table initializers and the start section. The name section
/// and DWARF aren't counted.
/// How many times the emitted module writes this function's index: in
/// `call`, `return_call` and `ref.func` instructions, exports, element
/// segments, global and table initializers and the start section. Custom
/// sections, including the name section and DWARF, aren't counted.

@@ -728,7 +861,7 @@ impl Emit for ModuleFunctions {
#[cfg(not(feature = "parallel"))]

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

The comment just above this hunk (line 856) says "functions is sorted largest first", which is now only true by default. Something like "functions is sorted largest first by default" would keep it accurate.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-ready The bot's review of its own PR found no concerns; ready for a human approval

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants