Note entrypoints

[bakkot]

The InitializeHostDefinedRealm, ParseScript, ScriptEvaluation, and ParseModule algorithms, as well as the Link and Evaluate methods of Cyclic Module Records, are all kind of weird: they are not called by the spec itself (except self-recursively), but rather are intended to be called by hosts as the entry points to the specification.

We should call that out.

Thanks to @rbuckton for raising this.

[jmdyck]

I brought this up a couple years ago, when those ops were in the process of becoming entry points: #1597 (comment)

(In addition to calling out their top-level-ness, I was also interested in having the spec say how hosts should/must invoke them. See this comment for rough wording, and this commit for spec-tastic wording.)

[jmdyck]

BTW, there are a few more operations that the spec doesn't invoke, but the host/implementation can:

• FinishDynamicImport
• DetachArrayBuffer
• ClearKeptObjects
• the WeakRef emptying thing

[syg]

It depends on what's meant by "entry point", is it entry points that have no ecma262 callers, or all entry points? Sounds like the latter?

The set of the latter is larger, and includes common AOs like Call and Construct.

I suppose for completeness we should include all the host hooks as well.

[bakkot]

• FinishDynamicImport
• DetachArrayBuffer
• ClearKeptObjects
• the WeakRef emptying thing

The spec tells you when hosts are expected to call FinishDynamicImport, ClearKeptObjects, and the WeakRef emptying thing, so I don't think they need any further calling out. And there's already a NOTE in DetachArrayBuffer which says

No operations defined by this specification use the DetachArrayBuffer abstract operation. However, an ECMAScript host or implementation may define such operations.

so I think it's fine too.

---

is it entry points that have no ecma262 callers

This is what I intended. Hosts can call whatever they want; it doesn't really make sense to try to list everything the host might call.

The host hooks are called by the spec rather than by hosts, so I wouldn't consider them entry points.