Skip to content

doc: clarify behaviour of node-api adjust function #57463

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

Merged
merged 14 commits into from
Mar 28, 2025
18 changes: 13 additions & 5 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -6126,16 +6126,24 @@ NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,
* `[in] env`: The environment that the API is invoked under.
* `[in] change_in_bytes`: The change in externally allocated memory that is kept
alive by JavaScript objects.
* `[out] result`: The adjusted value
* `[out] result`: The adjusted value. This value should reflect the
total amount of external memory with the given `change_in_bytes` included.
Implementations may use a single counter for all addons, or a
counter for each addon. The absolute value of the returned value should not
be depended on.

Returns `napi_ok` if the API succeeded.

This function gives V8 an indication of the amount of externally allocated
memory that is kept alive by JavaScript objects (i.e. a JavaScript object
that points to its own memory allocated by a native addon). Registering
externally allocated memory will trigger global garbage collections more
This function gives the runtime an indication of the amount of externally
allocated memory that is kept alive by JavaScript objects
(i.e. a JavaScript object that points to its own memory allocated by a
native addon). Registering externally allocated memory may, but is not
guaranteed to, trigger global garbage collections more
often than it would otherwise.

This function is expected to be invoked symmetrically. If it is invoked with +512KB,
it is expected to be invoked -512KB in sum at a later time.
Copy link
Member

Choose a reason for hiding this comment

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

I am still wondering if we should include the comment about calling with -512 if you called with +512 before. If its ok to call +512 twice and then -1024 later I'm not sure we want to include that.

"in sum" should address the concern? I think this sentence now is saying the value should be in symmetry.


## Promises

Node-API provides facilities for creating `Promise` objects as described in
Expand Down
Loading