Misleading information around await's interaction with microtask/task queues

[senocular]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await

What specific section or headline is this issue about?

Control flow effects of await

What information was incorrect, unhelpful, or incomplete?

...all code that depends on the expression's value is paused and pushed into the microtask queue.

await does not inherently push anything into the microtask queue, at least not unless the promise being awaited is already settled. The microtask queue is where promise tasks go after the promise is settled. await simply pauses the function. The microtask of resuming the function is added to the queue when the promise ultimately settles.

The "microtask queue" link to the EventLoop page also has no mention of the microtask queue.

The main thread is then freed for the next task in the event loop. This happens even if the awaited value is an already-resolved promise or not a promise.

This only happens if the promise is not already settled (or does not get settled within further execution of the current task). If settled, function continuation is added to the microtask queue and the current task of the event loop continues to run until its microtask queue is empty. You can create an event loop-blocking async function demonstrating this

// blocks the event loop
async function loop(){
  await Promise.resolve()
  loop()
}
loop()

Despite the use of await, the main thread is not freed to run the next task.

What did you expect to see?

A more accurate description await and its interactions with the task and microtask queues.

The microtask link is probably better directed to:
https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide
(see comment below)

Do you have any supporting links, references, or citations?

https://developer.mozilla.org/en-US/docs/Web/API/HTML_DOM_API/Microtask_guide

Do you have anything more you want to share?

No response

MDN metadata

Page report details

• Folder: en-us/web/javascript/reference/operators/await
• MDN URL: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await
• GitHub URL: https://github.com/mdn/content/blob/main/files/en-us/web/javascript/reference/operators/await/index.md
• Last commit: 0e1f404
• Document last modified: 2022-12-27T01:31:43.000Z

[Josh-Cena]

I agree there's something subtle about the phrasing here, but I won't be able to get to this soon. If you have solid ideas, feel free to send a PR.

The "microtask queue" link to the EventLoop page also has no mention of the microtask queue.

That's an unfortunate miss. I planned to add microtasks to the event loop page, but never got to it, which is why the link became dangling. I would prefer to keep it as-is, though, because this should be a core topic, not particularly an HTML topic (there's only one task queue in the language).

This only happens if the promise is not already settled (or does not get settled within further execution of the current task). If settled, function continuation is added to the microtask queue and the current task of the event loop continues to run until its microtask queue is empty. You can create an event loop-blocking async function demonstrating this

// blocks the event loop
async function loop(){
  await Promise.resolve()
  loop()
}
loop()

Despite the use of await, the main thread is not freed to run the next task.

Nice construction. I would love to see it on the page!