Attempt to remove implied-document definition

[dtapuska]

@bzbarsky has raised concerns a few times about the lack of formal definition of a task's document. The definition comes from the implied-document which is relatively handwavy.

Can we brainstorm some ideas how we can better formalize this?

For example I'm wondering if we can introduce a "queue a document task" and then we can change the call sites to "queue a document task given element's document". And then that could take the event loop from the document so we wouldn't need to use the definition of implied event loop either. Now that doesn't cover all the cases but would be a fair number of them.

[annevk]

That sounds great to me.

[domenic]

Yes, this would be lovely. It's just a ton of work. I count 202 uses of "queue a task" in HTML alone, not to mention the rest of the ecosystem. That said, @dtapuska has done heroic things before... and incremental progress is totally possible, i.e. we keep using implied document as a fallback until all call sites are updated.

I'm unsure whether we should introduce a new "queue a document task" + "queue a document microtask" or just reuse "queue a task" and add a semi-optional parameter. (I.e., it's mandatory in window event loops.) It's worth thinking about how this would impact cases that are polymorphic over event loops. There aren't many of these; maybe just BroadcastChannel's postMessage().

Anyway I think the right thing to do is figure out what the various call sites look like. Ideas:

Queue a task on the X task source, with document doc, to run the following steps:

Queue a task on the X task source of event loop, with document doc, to run the following steps:

Queue a task on the X task source of event loop to run the following steps. If event loop is a window event loop, this must be done with document doc.

(Only valid in worker event loops.) Queue a task on the X task source to run the following steps:

[dtapuska]

I think we should reopen this issue until they all land no? Not sure what the magic was that closed it in github but it didn't have closes in the commit msg I don't think.

[domenic]

Ah, I guess it was in the pull request description. Thanks for the heads-up.

[domenic]

I started working on this a bit more as another spec (portals) would benefit from it. However I ended up unsure what direction to go.

Recap:

• Each task needs an event loop, and if that event loop is a Window event loop, a document.
• HTML's callers generally have nearby access to one of:
  • A browsing context (e.g., during navigation and history traversal)
  • A global object (e.g., in setTimeout() or various worker situations)
  • A document (e.g., during history traversal we have entry's Document)
  • An element (e.g., all current uses of "queue an element task")
• The event loop is pretty trivial to compute from any of those inputs, so I'll gloss over that in what follows.

Here are some ideas:

1. Introduce "queue browsing context task" which takes a browsing context
   • It computes document as the BC's active document
2. Introduce "queue a global task" which takes a global object.
   • It computes document from the global object, if the global object is a Window, or null otherwise
   • If the caller has a Document, it needs to "queue a global task given document's relevant global object"
   • If the caller has a browsing context, it needs to "queue a global task given bc's WindowProxy's [[Window]] value", or alternately "queue a global task given bc's active document's relevant global object"
   • If the caller has an element, they will keep using "queue an element task". That's too common for us to require an indirection like "queue a global task using element's relevant global object"
3. Replace "queue an element task" with "queue an object task" which takes any platform object.
   • It computes the document from the object's relevant global object, if that relevant global object is a Window, or null otherwise. (Per spec an element's node document is always equal to its relevant global object, I am pretty sure?)
   • This is easy to use if the caller has a global object, a document, or an element
   • If the caller has a browsing context, they could do "queue an object task given bc's active document".
   • The name is kind of bad.

Currently I am leaning toward doing either (1) + (3), or just (3). Do folks have thoughts?

[annevk]

(Per spec an element's node document is always equal to its relevant global object, I am pretty sure?)

Per specifications, if you create a custom element in global A and move it into a document in global B, its relevant global object is A, but its node document's relevant global object is B.

Could we adjust queue a task itself to take a source, steps, and either a platform object or a event loop? And if you pass an event loop directly we assert it's not a window event loop? Not a big fan of allowing browsing contexts to be passed around as they don't carry authority.

[domenic]

Per specifications, if you create a custom element in global A and move it into a document in global B, its relevant global object is A, but its node document's relevant global object is B.

OK, so "queue an element task" should stick around.

Could we adjust queue a task itself to take a source, steps, and either a platform object or a event loop?

So, use overloading instead of separately-named algorithms? That's certainly possible, but I'm not sure it's better.

Not a big fan of allowing browsing contexts to be passed around as they don't carry authority.

I understand you dislike them, but I think asking people to do "queue a global task given bc's WindowProxy's [[Window]] value" is unnecessary ceremony and I don't think it's reasonable to require.

[annevk]

Yeah, perhaps "queue an element task" should stay separate. The other thing we could do is special case elements in "queue a task", but I suppose we could also assert you're not passing them.

I don't dislike browsing contexts, but they're just not the right target as they represent a sequence of targets. And encouraging people to think of them as if they're synonymous with their active document will create all kinds of bugs, in particular when queuing tasks from "in parallel" or some such.

[domenic]

I guess it's not so bad to require callers to do "bc's active document"; I forgot the part of my post where I mentioned that was an option.

I guess I see two possibilities now:

• "queue an object task"
• "queue a global task", but make it easy to go from browsing context -> global, e.g. define "browsing context's current Window". This would probably be a good change independently, actually...

I like the latter.

[annevk]

But would we eventually merge them into queue a task? Could you sketch what the eventual API here would look like? And why is it better to take a global than a platform object (of which a global is one)?

[domenic]

But would we eventually merge them into queue a task?

I don't think we'd eventually merge them, unless we really like overloading. (Which I don't, at least.)

Could you sketch what the eventual API here would look like?

It's as in #5653:

• "Queue a task" (task source, event loop, document-or-null, steps) is the base-level primitive
• "Queue a global task" (task source, global object, steps) is used for "global" things
• "Queue an element task" (task source, element, steps) is used for "element" things

And why is it better to take a global than a platform object (of which a global is one)?

Taking a generic platform object makes it too easy to do the wrong thing for elements, where (apparently) we want to use their node document instead of their relevant global object's associated Document. The price is that we sometimes have to say "queue a global task given X's relevant global object" instead of "queue an object task given X", but I think that's good. It also makes you consider whether you want to instead use the current global object.

[annevk]

Thanks, I guess that's reasonable. I was thinking we would keep element task and use an assert to keep elements out of the more generic variant, but this works.