Skip to content

vm: sync-ify SourceTextModule linkage #59000

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from

Conversation

legendecas
Copy link
Member

@legendecas legendecas commented Jul 8, 2025

Split module.link(linker) into two synchronous step
sourceTextModule.linkRequestedModules() and
sourceTextModule.instantiate(). This allows creating vm modules and
resolving the dependencies in a complete synchronous procedure.

This also makes syntheticModule.link() redundant. The link step for a
SyntheticModule is no-op and is already taken care in the constructor
by initializing the binding slots with the given export names.

This also enables (static) source phase import in vm.SourceTextModules.

Refs: #37648

@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/loaders
  • @nodejs/vm

@nodejs-github-bot nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. needs-ci PRs that need a full CI run. labels Jul 8, 2025
@legendecas legendecas added module Issues and PRs related to the module subsystem. vm Issues and PRs related to the vm subsystem. labels Jul 8, 2025
Split `module.link(linker)` into two synchronous step
`sourceTextModule.linkRequestedModules()` and
`sourceTextModule.instantiate()`. This allows creating vm modules and
resolving the dependencies in a complete synchronous procedure.

This also makes `syntheticModule.link()` redundant. The link step for a
SyntheticModule is no-op and is already taken care in the constructor
by initializing the binding slots with the given export names.
Copy link

codecov bot commented Jul 9, 2025

Codecov Report

Attention: Patch coverage is 78.18182% with 12 lines in your changes missing coverage. Please review.

Project coverage is 90.07%. Comparing base (4de0197) to head (9c18d11).
Report is 1 commits behind head on main.

Files with missing lines Patch % Lines
lib/internal/vm/module.js 76.31% 8 Missing and 1 partial ⚠️
src/module_wrap.cc 78.57% 1 Missing and 2 partials ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #59000      +/-   ##
==========================================
+ Coverage   90.04%   90.07%   +0.03%     
==========================================
  Files         641      641              
  Lines      188846   188898      +52     
  Branches    37039    37052      +13     
==========================================
+ Hits       170040   170151     +111     
+ Misses      11504    11453      -51     
+ Partials     7302     7294       -8     
Files with missing lines Coverage Δ
lib/internal/errors.js 97.50% <100.00%> (+<0.01%) ⬆️
src/module_wrap.h 44.44% <ø> (ø)
src/node_errors.h 87.50% <ø> (ø)
src/module_wrap.cc 73.66% <78.57%> (+0.50%) ⬆️
lib/internal/vm/module.js 96.24% <76.31%> (-2.15%) ⬇️

... and 39 files with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Comment on lines +950 to +951
The order of the `modules` array should respect the order of
[`sourceTextModule.moduleRequests`][].
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
The order of the `modules` array should respect the order of
[`sourceTextModule.moduleRequests`][].
The order of the module instances in the `modules` array should correspond to the order of
[`sourceTextModule.moduleRequests`][] being resolved.

@@ -369,6 +371,37 @@ class SourceTextModule extends Module {
}
}

linkRequestedModules(modules) {
validateThisInternalField(this, kWrap, 'SyntheticModule');
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
validateThisInternalField(this, kWrap, 'SyntheticModule');
validateThisInternalField(this, kWrap, 'SourceTextModule');

}
return module[kWrap];
});
this[kWrap].link(moduleWraps);
Copy link
Member

@joyeecheung joyeecheung Jul 9, 2025

Choose a reason for hiding this comment

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

I wonder if the separation of two methods is actually necessary? This just stashes the wraps into an internal map. It seems fine to just merge all this into instantiate() and only do the conversion when instantiation happens. Users can maintain an array themselves before calling instantiate() and that doesn't seem to make a whole lot of difference - the map is not really visible to them anyway. In return the API would look simpler and users can be more flexible in how they maintain that array e.g. fill them in a non-consecutive way, or modify them as much as needed.

On a related note, I don't think the resolve cache even strictly has to be in C++ land. The current way of managing the cache using a v8::Global may be leak prone since V8 doesn't necessary know that a specific Module wrap is the only one that holds a bunch others alive - it just sees a bunch of v8::Global "out of nowhere" because V8's GC can't trace what that map is doing in C++ obviously. That might be the cause of #50113 (or that was my conclusion ~2 years ago: #50113 (comment)). Moving the cache to JS land might make it go away since then V8 would be able to understand all the inter-module-wrap references. And if it's in JS land, the linkRequestedModules() isn't strictly necessary because there might be better ways to interact with the cache. It looks more like a design that's specifically tailored to how we currently manage this cache, which is more of a thing that just happened but is not necessarily optimal design-wise.

Copy link
Member Author

Choose a reason for hiding this comment

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

It is necessary to split to link and instantiate to support cyclic module requests. Please have a look at test/parallel/test-vm-module-instantiate.js.

Copy link
Member Author

@legendecas legendecas Jul 10, 2025

Choose a reason for hiding this comment

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

The resolve cache will be cleared immediately when instantiate is invoked. It is only intended to be easily referenced in the ResolveModuleCallback from V8. If a SourceTextModule is correctly invoked with instantiate after linkRequestedModules, the resolve cache should not keep the modules alive indefinitely.

node/src/module_wrap.cc

Lines 615 to 616 in e3e739d

// clear resolve cache on instantiate
obj->resolve_cache_.clear();

For #50113, I think an OOM can be reproduced without link or evaluate: #50113 (comment).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
c++ Issues and PRs that require attention from people who are familiar with C++. lib / src Issues and PRs related to general changes in the lib or src directory. module Issues and PRs related to the module subsystem. needs-ci PRs that need a full CI run. vm Issues and PRs related to the vm subsystem.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants