FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

src: disambiguate terms used to refer to builtins and addons · nodejs/node@fbc52e5 · GitHub

/ node Public

Commit fbc52e5

Browse files
joyeecheung
authored and
richardlau
committed
src: disambiguate terms used to refer to builtins and addons
The term "native module" dates back to some of the oldest code in the code base. Within the context of Node.js core it usually refers to modules that are native to Node.js (e.g. fs, http), but it can cause confusion for people who don't work on this part of the code base, as "native module" can also refer to native addons - which is even the case in some of the API docs and error messages. This patch tries to make the usage of these terms more consistent. Now within the context of Node.js core: - JavaScript scripts that are built-in to Node.js are now referred to as "built-in(s)". If they are available as modules, they can also be referred to as "built-in module(s)". - Dynamically-linked shared objects that are loaded into the Node.js processes are referred to as "addons". We will try to avoid using the term "native modules" because it could be ambiguous. Changes in this patch: File names: - node_native_module.h -> node_builtins.h, - node_native_module.cc -> node_builtins.cc C++ binding names: - `native_module` -> `builtins` `node::Environment`: - `native_modules_without_cache` -> `builtins_without_cache` - `native_modules_with_cache` -> `builtins_with_cache` - `native_modules_in_snapshot` -> `builtins_in_cache` - `native_module_require` -> `builtin_module_require` `node::EnvSerializeInfo`: - `native_modules` -> `builtins `node::native_module::NativeModuleLoader`: - `native_module` namespace -> `builtins` namespace - `NativeModuleLoader` -> `BuiltinLoader` - `NativeModuleRecordMap` -> `BuiltinSourceMap` - `NativeModuleCacheMap` -> `BuiltinCodeCacheMap` - `ModuleIds` -> `BuiltinIds` - `ModuleCategories` -> `BuiltinCategories` - `LoadBuiltinModuleSource` -> `LoadBuiltinSource` `loader.js`: - `NativeModule` -> `BuiltinModule` (the `NativeModule` name used in `process.moduleLoadList` is kept for compatibility) And other clarifications in the documentation and comments. PR-URL: #44135 Backport-PR-URL: #45663 Fixes: #44036 Reviewed-By: Jacob Smith <jacob@frende.me> Reviewed-By: Matteo Collina <matteo.collina@gmail.com> Reviewed-By: Michael Dawson <midawson@redhat.com> Reviewed-By: Richard Lau <rlau@redhat.com> Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com> Reviewed-By: Mohammed Keyvanzadeh <mohammadkeyvanzade94@gmail.com> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Jan Krems <jan.krems@gmail.com>
1 parent 953072d commit fbc52e5

48 files changed

Lines changed: 297 additions & 295 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@
108108
/benchmark/misc/startup.js @nodejs/startup
109109
/src/node.cc @nodejs/startup
110110
/src/node_code_cache_stub.cc @nodejs/startup
111-
/src/node_native_module* @nodejs/startup
111+
/src/node_builtins* @nodejs/startup
112112
/src/node_snapshot* @nodejs/startup
113113
/lib/internal/bootstrap/* @nodejs/startup
114114
/tools/code_cache/* @nodejs/startup

‎doc/api/deprecations.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2003,7 +2003,7 @@ changes:
20032003

20042004
Type: Compile-time
20052005

2006-
Certain versions of `node::MakeCallback` APIs available to native modules are
2006+
Certain versions of `node::MakeCallback` APIs available to native addons are
20072007
deprecated. Please use the versions of the API that accept an `async_context`
20082008
parameter.
20092009

@@ -2751,7 +2751,7 @@ changes:
27512751
Type: Documentation-only
27522752

27532753
The `node:repl` module exports a `_builtinLibs` property that contains an array
2754-
with native modules. It was incomplete so far and instead it's better to rely
2754+
of built-in modules. It was incomplete so far and instead it's better to rely
27552755
upon `require('node:module').builtinModules`.
27562756

27572757
### DEP0143: `Transform._transformState`

‎doc/api/modules.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -705,8 +705,8 @@ This does not apply to [native addons][], for which reloading will result in an
705705
error.
706706

707707
Adding or replacing entries is also possible. This cache is checked before
708-
native modules and if a name matching a native module is added to the cache,
709-
only `node:`-prefixed require calls are going to receive the native module.
708+
built-in modules and if a name matching a built-in module is added to the cache,
709+
only `node:`-prefixed require calls are going to receive the built-in module.
710710
Use with care!
711711

712712
<!-- eslint-disable node-core/no-duplicate-requires -->

‎doc/api/n-api.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -201,9 +201,9 @@ GitHub projects using CMake.js.
201201
#### prebuildify
202202

203203
[prebuildify][] is a tool based on node-gyp. The advantage of prebuildify is
204-
that the built binaries are bundled with the native module when it's
204+
that the built binaries are bundled with the native addon when it's
205205
uploaded to npm. The binaries are downloaded from npm and are immediately
206-
available to the module user when the native module is installed.
206+
available to the module user when the native addon is installed.
207207

208208
## Usage
209209

@@ -1381,7 +1381,7 @@ callback throws an exception with no way to recover.
13811381

13821382
### Fatal errors
13831383

1384-
In the event of an unrecoverable error in a native module, a fatal error can be
1384+
In the event of an unrecoverable error in a native addon, a fatal error can be
13851385
thrown to immediately terminate the process.
13861386

13871387
#### `napi_fatal_error`
@@ -5745,7 +5745,7 @@ Returns `napi_ok` if the API succeeded.
57455745

57465746
This function gives V8 an indication of the amount of externally allocated
57475747
memory that is kept alive by JavaScript objects (i.e. a JavaScript object
5748-
that points to its own memory allocated by a native module). Registering
5748+
that points to its own memory allocated by a native addon). Registering
57495749
externally allocated memory will trigger global garbage collections more
57505750
often than it would otherwise.
57515751

‎doc/contributing/adding-new-napi-api.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Contributing a new API to Node-API
22

3-
Node-API is the next-generation ABI-stable API for native modules.
3+
Node-API is the next-generation ABI-stable API for native addons.
44
While improving the API surface is encouraged and welcomed, the following are
55
a set of principles and guidelines to keep in mind while adding a new
66
Node-API.

‎lib/assert.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ const { openSync, closeSync, readSync } = require('fs');
6565
const { inspect } = require('internal/util/inspect');
6666
const { isPromise, isRegExp } = require('internal/util/types');
6767
const { EOL } = require('internal/constants');
68-
const { NativeModule } = require('internal/bootstrap/loaders');
68+
const { BuiltinModule } = require('internal/bootstrap/loaders');
6969
const { isError } = require('internal/util');
7070

7171
const errorCache = new SafeMap();
@@ -303,7 +303,7 @@ function getErrMessage(message, fn) {
303303

304304
// Skip Node.js modules!
305305
if (StringPrototypeStartsWith(filename, 'node:') &&
306-
NativeModule.exists(StringPrototypeSlice(filename, 5))) {
306+
BuiltinModule.exists(StringPrototypeSlice(filename, 5))) {
307307
errorCache.set(identifier, undefined);
308308
return;
309309
}

‎lib/internal/bootstrap/loaders.js‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424
// and have their nm_flags set to NM_F_INTERNAL.
2525
//
2626
// Internal JavaScript module loader:
27-
// - NativeModule: a minimal module system used to load the JavaScript core
27+
// - BuiltinModule: a minimal module system used to load the JavaScript core
2828
// modules found in lib/**/*.js and deps/**/*.js. All core modules are
2929
// compiled into the node binary via node_javascript.cc generated by js2c.py,
3030
// so they can be loaded faster without the cost of I/O. This class makes the
@@ -180,9 +180,9 @@ let internalBinding;
180180

181181
const loaderId = 'internal/bootstrap/loaders';
182182
const {
183-
moduleIds,
183+
builtinIds,
184184
compileFunction
185-
} = internalBinding('native_module');
185+
} = internalBinding('builtins');
186186

187187
const getOwn = (target, property, receiver) => {
188188
return ObjectPrototypeHasOwnProperty(target, property) ?
@@ -195,13 +195,13 @@ const getOwn = (target, property, receiver) => {
195195
* Be careful not to expose this to user land unless --expose-internals is
196196
* used, in which case there is no compatibility guarantee about this class.
197197
*/
198-
class NativeModule {
198+
class BuiltinModule {
199199
/**
200200
* A map from the module IDs to the module instances.
201-
* @type {Map<string, NativeModule>}
201+
* @type {Map<string, BuiltinModule>}
202202
*/
203203
static map = new SafeMap(
204-
ArrayPrototypeMap(moduleIds, (id) => [id, new NativeModule(id)])
204+
ArrayPrototypeMap(builtinIds, (id) => [id, new BuiltinModule(id)])
205205
);
206206

207207
constructor(id) {
@@ -216,7 +216,7 @@ class NativeModule {
216216
this.loading = false;
217217

218218
// The following properties are used by the ESM implementation and only
219-
// initialized when the native module is loaded by users.
219+
// initialized when the built-in module is loaded by users.
220220
/**
221221
* The C++ ModuleWrap binding used to interface with the ESM implementation.
222222
* @type {ModuleWrap|undefined}
@@ -232,7 +232,7 @@ class NativeModule {
232232
// To be called during pre-execution when --expose-internals is on.
233233
// Enables the user-land module loader to access internal modules.
234234
static exposeInternals() {
235-
for (const { 0: id, 1: mod } of NativeModule.map) {
235+
for (const { 0: id, 1: mod } of BuiltinModule.map) {
236236
// Do not expose this to user land even with --expose-internals.
237237
if (id !== loaderId) {
238238
mod.canBeRequiredByUsers = true;
@@ -241,11 +241,11 @@ class NativeModule {
241241
}
242242

243243
static exists(id) {
244-
return NativeModule.map.has(id);
244+
return BuiltinModule.map.has(id);
245245
}
246246

247247
static canBeRequiredByUsers(id) {
248-
const mod = NativeModule.map.get(id);
248+
const mod = BuiltinModule.map.get(id);
249249
return mod && mod.canBeRequiredByUsers;
250250
}
251251

@@ -326,13 +326,17 @@ class NativeModule {
326326
requireWithFallbackInDeps : nativeModuleRequire;
327327

328328
const fn = compileFunction(id);
329+
// Arguments must match the parameters specified in
330+
// BuiltinLoader::LookupAndCompile().
329331
fn(this.exports, requireFn, this, process, internalBinding, primordials);
330332

331333
this.loaded = true;
332334
} finally {
333335
this.loading = false;
334336
}
335337

338+
// "NativeModule" is a legacy name of "BuiltinModule". We keep it
339+
// here to avoid breaking users who parse process.moduleLoadList.
336340
ArrayPrototypePush(moduleLoadList, `NativeModule ${id}`);
337341
return this.exports;
338342
}
@@ -342,7 +346,7 @@ class NativeModule {
342346
// written in CommonJS style.
343347
const loaderExports = {
344348
internalBinding,
345-
NativeModule,
349+
BuiltinModule,
346350
require: nativeModuleRequire
347351
};
348352

@@ -351,7 +355,7 @@ function nativeModuleRequire(id) {
351355
return loaderExports;
352356
}
353357

354-
const mod = NativeModule.map.get(id);
358+
const mod = BuiltinModule.map.get(id);
355359
// Can't load the internal errors module from here, have to use a raw error.
356360
// eslint-disable-next-line no-restricted-syntax
357361
if (!mod) throw new TypeError(`Missing internal module '${id}'`);
@@ -361,7 +365,7 @@ function nativeModuleRequire(id) {
361365
// Allow internal modules from dependencies to require
362366
// other modules from dependencies by providing fallbacks.
363367
function requireWithFallbackInDeps(request) {
364-
if (!NativeModule.map.has(request)) {
368+
if (!BuiltinModule.map.has(request)) {
365369
request = `internal/deps/${request}`;
366370
}
367371
return nativeModuleRequire(request);

‎lib/internal/bootstrap/node.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
// `MessagePort` implementation.
3535
// - `lib/internal/bootstrap/loaders.js`: this sets up internal binding and
3636
// module loaders, including `process.binding()`, `process._linkedBinding()`,
37-
// `internalBinding()` and `NativeModule`.
37+
// `internalBinding()` and `BuiltinModule`.
3838
//
3939
// The initialization done in this script is included in both the main thread
4040
// and the worker threads. After this, further initialization is done based
@@ -102,7 +102,7 @@ process.domain = null;
102102
process._exiting = false;
103103

104104
// process.config is serialized config.gypi
105-
const nativeModule = internalBinding('native_module');
105+
const nativeModule = internalBinding('builtins');
106106

107107
// TODO(@jasnell): Once this has gone through one full major
108108
// release cycle, remove the Proxy and setter and update the

‎lib/internal/bootstrap/pre_execution.js‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,7 @@ function initializeReport() {
290290
function setupDebugEnv() {
291291
require('internal/util/debuglog').initializeDebugEnv(process.env.NODE_DEBUG);
292292
if (getOptionValue('--expose-internals')) {
293-
require('internal/bootstrap/loaders').NativeModule.exposeInternals();
293+
require('internal/bootstrap/loaders').BuiltinModule.exposeInternals();
294294
}
295295
}
296296

@@ -512,8 +512,8 @@ function initializePolicy() {
512512
}
513513

514514
function initializeWASI() {
515-
const { NativeModule } = require('internal/bootstrap/loaders');
516-
const mod = NativeModule.map.get('wasi');
515+
const { BuiltinModule } = require('internal/bootstrap/loaders');
516+
const mod = BuiltinModule.map.get('wasi');
517517
mod.canBeRequiredByUsers =
518518
getOptionValue('--experimental-wasi-unstable-preview1');
519519
}

‎lib/internal/debugger/inspect_repl.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,8 +117,8 @@ function extractFunctionName(description) {
117117
}
118118

119119
const {
120-
moduleIds: PUBLIC_BUILTINS,
121-
} = internalBinding('native_module');
120+
builtinIds: PUBLIC_BUILTINS,
121+
} = internalBinding('builtins');
122122
const NATIVES = internalBinding('natives');
123123
function isNativeUrl(url) {
124124
url = RegExpPrototypeSymbolReplace(/\.js$/, url, '');

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL