From 385510bae631ec3468d2fa0d1ac2539e54d615ca Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Fri, 26 Oct 2018 09:52:12 +1100 Subject: [PATCH 1/2] doc: remove "idiomatic choice" from queueMicrotask It can't be idiomatic if it's not in general use and therefore hasn't been picked up by users. It's not even in browsers yet. "Idiomatic" use is an emergent property that comes from observed use and this feature is so new (to browsers and Node) that it can't possibly be. In general I don't think it's the place of the Node API docs to observe what emerges as idiomatic Node.js. It also can't be a recommended feature (if that was the intent of the language) because it's marked experimental. For now, it's just a feature, nothing more. Recommendations and/or observations about it being 'idiomatic' can come later. --- doc/api/globals.md | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/api/globals.md b/doc/api/globals.md index e41d621883184b..ed0ad153d5e14c 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -122,7 +122,6 @@ The `queueMicrotask()` method queues a microtask to invoke `callback`. If `callback` throws an exception, the [`process` object][] `'uncaughtException'` event will be emitted. -In general, `queueMicrotask` is the idiomatic choice over `process.nextTick()`. `process.nextTick()` will always run before the microtask queue, and so unexpected execution order may be observed. From a6da5fd3c07c9556475a1a209ed7f90004f0f452 Mon Sep 17 00:00:00 2001 From: Rod Vagg Date: Mon, 29 Oct 2018 20:16:07 +1100 Subject: [PATCH 2/2] fixup! doc: remove "idiomatic choice" from queueMicrotask --- doc/api/globals.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/api/globals.md b/doc/api/globals.md index ed0ad153d5e14c..22699f035e53b0 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -122,8 +122,10 @@ The `queueMicrotask()` method queues a microtask to invoke `callback`. If `callback` throws an exception, the [`process` object][] `'uncaughtException'` event will be emitted. -`process.nextTick()` will always run before the microtask queue, and so -unexpected execution order may be observed. +The microtask queue is managed by V8 and may be used in a similar manner to +the `process.nextTick()` queue, which is managed by Node.js. The +`process.nextTick()` queue is always processed before the microtask queue +within each turn of the Node.js event loop. ```js // Here, `queueMicrotask()` is used to ensure the 'load' event is always