src: add Realm document in the src README.md #47932

legendecas · 2023-05-09T09:39:26Z

Document the current Environment/Realm definitions.

src/README.md

legendecas · 2023-05-10T08:20:58Z

@cjihrig @VoltrexKeyva Updated. Thank you for the suggestions!

src/README.md

joyeecheung · 2023-05-09T11:22:33Z

src/README.md

-It also provides [cleanup hooks][] and maintains a list of [`BaseObject`][]
-instances.
+different built-in modules that can be shared across different `Realm`
+instances, for example a libuv timer for `setTimeout()`.


Should they actually share timers? I think the timer callbacks are tied to specific contexts too? Though I guess the event loop could be shared.

Yeah, it would actually be very helpful to spell out what properties are being shared between different Realms for the same Environment and which not. I've seen a bunch of PRs that move properties from the Environment to the individual Realms, but it's not really clear where the line is and whether we're not essentially just introducing the ability to have multiple Environments similar to #47855.

Thanks for pointing this out! I've added a list of examples that can be shared across realms with an Environment.

It is still yet to be done to share the async hook info between the realms -- it is necessary to link the async continuation between realm boundaries for AsyncLocalStorage to propagate correctly. This is essential to allow JS object access between multiple execution "environments" on the same thread.

I’m not really sure that this answers the question. How is the end state of Realm going to be different from what Environment is (or used to be before Realms were introduced)?

The difference between the end state of the Realm and the Environment would be:

An Environment is associated with an Isolate and provides the per-isolate hooks and APIs, and per-thread states, for instance, inspector agents, profilers, and APIs like RequestInterrupt() and can_call_into_js().

A Realm is associated with a Context and consists of a global object and can be extended as a principal realm or a synthetic realm. Each Environment has a single principal realm as its entry.

As realms share the Environment instance, we don't have to create inspector IO threads, or profiler connections for each realm. The async local storage needs to be propagated across async boundaries in another Realm of an Environment too.

Additionally, a Realm must be able to be repetitively created on the same Isolate and weakly referenced to properly support the ECMAScript ShadowRealm API.

As a conclusion, it is necessary to split the Realm and Environment to distinguish per-isolate states and per-context states.

An Environment is associated with an Isolate and provides the per-isolate hooks and APIs,

You’re describing IsolateData here, though.

You’re describing IsolateData here, though.

Yes, it's true that IsolateData is also associated with an Isolate. However, as documented, IsolateData acts like a string table and contains information (e.g. startup snapshot data) about the isolate. It has its distinct properties compared to an Environment.

Compared to IsolateData, Environment at the end state contains the necessary handles (bootstrapped with the principal realm) to propagate events across realm boundaries, for instance, propagating async local storages and promise rejection events from ShadowRealm.

I think the current state we have is:

There is IsolateData which is meant to hold per-isolate data

There are Realms with are meant to hold per-context data

There is Environment which has been a hotch-potch structure that people dump everything on since forever, so it contains both per-isolate data and per-context data (for the main context) in practice.

What we've been trying to do is to move per-isolate data in Environment to IsolateData and per-context data to Realm, it's happening but it's really not there yet.

@addaleax do you think your question has been answered?

src/README.md

legendecas · 2023-05-22T16:43:01Z

@joyeecheung @addaleax would you mind taking a look at this again? Thank you! <3

nodejs-github-bot · 2023-05-31T15:15:31Z

Commit Queue failed

- Loading data for nodejs/node/pull/47932
✔  Done loading data for nodejs/node/pull/47932
----------------------------------- PR info ------------------------------------
Title      src: add Realm document in the src README.md (#47932)
   ⚠  Could not retrieve the email or name of the PR author's from user's GitHub profile!
Branch     legendecas:shadow-realm/src-readme -> nodejs:main
Labels     c++, doc, needs-ci, realm
Commits    3
 - src: add Realm document in the src README.md
 - fixup! src: add Realm document in the src README.md
 - fixup! src: add Realm document in the src README.md
Committers 1
 - Chengzhong Wu 
PR-URL: https://github.com/nodejs/node/pull/47932
Reviewed-By: Colin Ihrig 
Reviewed-By: James M Snell 
Reviewed-By: Joyee Cheung 
------------------------------ Generated metadata ------------------------------
PR-URL: https://github.com/nodejs/node/pull/47932
Reviewed-By: Colin Ihrig 
Reviewed-By: James M Snell 
Reviewed-By: Joyee Cheung 
--------------------------------------------------------------------------------
   ℹ  This PR was created on Tue, 09 May 2023 09:39:26 GMT
   ✔  Approvals: 3
   ✔  - Colin Ihrig (@cjihrig) (TSC): https://github.com/nodejs/node/pull/47932#pullrequestreview-1418601961
   ✔  - James M Snell (@jasnell) (TSC): https://github.com/nodejs/node/pull/47932#pullrequestreview-1449806356
   ✔  - Joyee Cheung (@joyeecheung) (TSC): https://github.com/nodejs/node/pull/47932#pullrequestreview-1446049565
   ✔  Last GitHub CI successful
   ✘  No Jenkins CI runs detected
--------------------------------------------------------------------------------
   ✔  Aborted `git node land` session in /home/runner/work/node/node/.ncu

https://github.com/nodejs/node/actions/runs/5134609431

nodejs-github-bot · 2023-05-31T15:20:37Z

CI: https://ci.nodejs.org/job/node-test-pull-request/52024/

nodejs-github-bot · 2023-06-01T03:56:19Z

CI: https://ci.nodejs.org/job/node-test-pull-request/52042/

nodejs-github-bot · 2023-06-01T05:51:30Z

CI: https://ci.nodejs.org/job/node-test-pull-request/52045/

nodejs-github-bot · 2023-06-01T07:11:41Z

Landed in d57dd70

PR-URL: #47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: nodejs#47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: #47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

PR-URL: nodejs#47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

src: add Realm document in the src README.md

f0da57c

nodejs-github-bot added c++ Issues and PRs that require attention from people who are familiar with C++. needs-ci PRs that need a full CI run. labels May 9, 2023

legendecas added doc Issues and PRs related to the documentations. realm Issues and PRs related to the ShadowRealm API and node::Realm labels May 9, 2023

cjihrig approved these changes May 9, 2023

View reviewed changes

src/README.md Outdated Show resolved Hide resolved

src/README.md Outdated Show resolved Hide resolved

src/README.md Outdated Show resolved Hide resolved

src/README.md Outdated Show resolved Hide resolved

VoltrexKeyva reviewed May 9, 2023

View reviewed changes

src/README.md Outdated Show resolved Hide resolved

jasnell approved these changes May 10, 2023

View reviewed changes

fixup! src: add Realm document in the src README.md

136cf14

joyeecheung reviewed May 10, 2023

View reviewed changes

This comment was marked as off-topic.

Sign in to view

fixup! src: add Realm document in the src README.md

a907870

legendecas force-pushed the shadow-realm/src-readme branch from d154353 to a907870 Compare May 16, 2023 12:01

joyeecheung approved these changes May 26, 2023

View reviewed changes

jasnell approved these changes May 29, 2023

View reviewed changes

legendecas added the commit-queue Add this label to land a pull request using GitHub Actions. label May 31, 2023

nodejs-github-bot added commit-queue-failed An error occurred while landing this pull request using GitHub Actions. and removed commit-queue Add this label to land a pull request using GitHub Actions. labels May 31, 2023

legendecas added the request-ci Add this label to start a Jenkins CI on a PR. label May 31, 2023

github-actions bot removed the request-ci Add this label to start a Jenkins CI on a PR. label May 31, 2023

legendecas removed the commit-queue-failed An error occurred while landing this pull request using GitHub Actions. label Jun 1, 2023

legendecas added the commit-queue Add this label to land a pull request using GitHub Actions. label Jun 1, 2023

nodejs-github-bot removed the commit-queue Add this label to land a pull request using GitHub Actions. label Jun 1, 2023

nodejs-github-bot merged commit d57dd70 into nodejs:main Jun 1, 2023
54 checks passed

github-actions bot mentioned this pull request Jun 2, 2023

CI Reliability 2023-06-02 nodejs/reliability#583

Open

34 tasks

legendecas deleted the shadow-realm/src-readme branch June 2, 2023 10:02

This was referenced Jun 3, 2023

CI Reliability 2023-06-03 nodejs/reliability#584

Open

CI Reliability 2023-06-04 nodejs/reliability#585

Open

targos pushed a commit that referenced this pull request Jun 4, 2023

src: add Realm document in the src README.md

9a03474

PR-URL: #47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

targos mentioned this pull request Jun 4, 2023

v20.3.0 release proposal #48332

Merged

github-actions bot mentioned this pull request Jun 5, 2023

CI Reliability 2023-06-05 nodejs/reliability#586

Open

30 tasks

danielleadams pushed a commit that referenced this pull request Jul 6, 2023

src: add Realm document in the src README.md

ecc02e3

PR-URL: #47932 Reviewed-By: Colin Ihrig <cjihrig@gmail.com> Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Joyee Cheung <joyeec9h3@gmail.com>

danielleadams mentioned this pull request Jul 10, 2023

v18.17.0 release proposal #48694

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

src: add Realm document in the src README.md #47932

src: add Realm document in the src README.md #47932

legendecas commented May 9, 2023

legendecas commented May 10, 2023

joyeecheung May 9, 2023

addaleax May 11, 2023

legendecas May 16, 2023

addaleax May 16, 2023

legendecas May 18, 2023 •

edited

addaleax May 22, 2023

legendecas May 26, 2023

joyeecheung May 26, 2023 •

edited

legendecas May 30, 2023

This comment was marked as off-topic.

legendecas commented May 22, 2023

nodejs-github-bot commented May 31, 2023

nodejs-github-bot commented May 31, 2023

nodejs-github-bot commented Jun 1, 2023

nodejs-github-bot commented Jun 1, 2023

nodejs-github-bot commented Jun 1, 2023

src: add Realm document in the src README.md #47932

src: add Realm document in the src README.md #47932

Conversation

legendecas commented May 9, 2023

legendecas commented May 10, 2023

joyeecheung May 9, 2023

Choose a reason for hiding this comment

addaleax May 11, 2023

Choose a reason for hiding this comment

legendecas May 16, 2023

Choose a reason for hiding this comment

addaleax May 16, 2023

Choose a reason for hiding this comment

legendecas May 18, 2023 • edited

Choose a reason for hiding this comment

addaleax May 22, 2023

Choose a reason for hiding this comment

legendecas May 26, 2023

Choose a reason for hiding this comment

joyeecheung May 26, 2023 • edited

Choose a reason for hiding this comment

legendecas May 30, 2023

Choose a reason for hiding this comment

This comment was marked as off-topic.

legendecas commented May 22, 2023

nodejs-github-bot commented May 31, 2023

nodejs-github-bot commented May 31, 2023

nodejs-github-bot commented Jun 1, 2023

nodejs-github-bot commented Jun 1, 2023

nodejs-github-bot commented Jun 1, 2023

legendecas May 18, 2023 •

edited

joyeecheung May 26, 2023 •

edited