Multiple globals and you

Have you ever encountered mysterious terms like "incumbent settings object", "entry global", or "current realm" while reading specs? Perhaps you even were writing a spec, and ended up using one of these phrases yourself---without _really_ knowing what it means? This post is for you. Please read at least the first part of it, up until "what's next."

With lots of help from Boris, I've worked to update HTML to be much more explicit and clear about what exactly these concepts are. The long version is at https://html.spec.whatwg.org/multipage/webappapis.html#realms-settings-objects-global-object. Here is the short version:

- Realm <-> environment settings object <-> global object; these are all 1:1:1
  - "Global object": what web developers see
  - "Environment settings object": what most web specs deal with
  - "Realm": what the JavaScript spec deals with

- There are generally >=4 potential realms/settings objects/global objects in any given algorithm:
  - Entry
  - Incumbent
  - Current
  - Relevant (there are generally >=1 of these)

(All four of these can be different at any given time due to iframe shenanigans; the link above gives a contrived example.)

Here's the important bit:

DON'T USE ENTRY AND INCUMBENT IN NEW SPECS. These concepts are strange and unintuitive and should be considered deprecated. You should not need to bother understanding them.

You _should_ work to understand the difference between current and relevant, and when you should use each. Please read the link above for that. (The basics: use current by default; use relevant for storing long-lived things.)



### What's next: the great incumbent/entry purge

If you are currently writing a spec that uses incumbent or entry: let's fix it! It is usually not too late; it is likely very little code in the wild is invoking your spec in multi-global situations, much less multi-global situations where you can actually distinguish entry or incumbent from current or relevant.

But, you might ask: what about all those older specs, like HTML, already using incumbent and entry? Well! We're hoping to fix them. If we can. This will be a long process involving writing lots of test cases where 4+ globals are in play, and seeing what global browsers actually use where the specs currently say incumbent or entry. If the result is not consistently incumbent or entry, we'll try to fix the spec to be current or relevant as appropriate, add the appropriate test case to web-platform-tests, and file bugs on browsers until everyone is on the same page. We suspect that in many cases the spec's current use of incumbent or entry does not match browser reality, so there's hope that this purge will go well.

This effort is in general tracked by two bugs:

- Incumbent: https://github.com/whatwg/html/issues/1430
- Entry: https://github.com/whatwg/html/issues/1431

If you want to join the entry/incumbent purge, feel free to ping us in those bugs and we'll help your spec out too. These tracking issues are not just for HTML.



### Other notes

Besides the entry/incumbent purge, there are a few remaining related items in this area. All but the first have to do with fixing or tweaking the definition of entry and incumbent in edge cases, and will become less important if we can successfully purge entry/incumbent from any security-sensitive checks (like origin checks).

#### Fixing "report an exception"

https://github.com/whatwg/html/issues/958

Right now it is very unclear to which global exceptions should be reported, when they occur. We have a plan for fixing this by making it work automatically when you use Web IDL to invoke callbacks most of the time, and forcing you to explicitly specify the global the rest of the time.

#### Ensuring all calls to user code correctly set up entry/incumbent

https://github.com/whatwg/html/issues/855

When you use Web IDL's callback types, and its algorithms for invoking them, the entry and incumbent concepts get tracked correctly, via "prepare to run a script" (entry) and "prepare to run a callback" (incumbent).

In some rare cases (structured clone, custom element callbacks, ...) web specs directly call into JavaScript code, using JS abstract operations like Call(function) or Invoke(obj, "method"). In this case the spec needs to carefully do the preparation (and cleanup) steps manually. Currently, many of them do not.

#### Fixing promise job enqueuing and how it affects entry

https://github.com/whatwg/html/issues/1426

Because of how promises are specced, they don't go through the usual Web IDL invoke-a-callback mechanism, and so they don't get their entry settings object set up correctly. We should fix that.

#### Removing the requirement that every object to have a realm (affects entry)

https://github.com/tc39/ecma262/issues/573

Currently Web IDL has a somewhat-vague requirement that every JavaScript object have a realm. This is largely to handle callback interfaces, e.g. cases like addEventListener("foo", arbitraryObj), where we need to grab a realm from arbitraryObj. The V8 team, at least, would prefer not to track the realm of every object (leaving only platform objects and functions as always having a realm), but this would slightly change the meaning of the entry concept in some cases. We're still working through what the best ideas are here.

### Thanks

If you got this far, you're awesome!

Received on Wednesday, 22 June 2016 19:59:11 UTC