@@ -1699,6 +1699,70 @@ function definitelyAsync(arg, cb) { |
1699 | 1699 | } |
1700 | 1700 | ``` |
1701 | 1701 |
|
| 1702 | +### When to use `queueMicrotask()` vs. `process.nextTick()` |
| 1703 | + |
| 1704 | +The [`queueMicrotask()`][] API is an alternative to `process.nextTick()` that |
| 1705 | +also defers execution of a function using the same microtask queue used to |
| 1706 | +execute the then, catch, and finally handlers of resolved promises. Within |
| 1707 | +Node.js, every time the "next tick queue" is drained, the microtask queue |
| 1708 | +is drained immediately after. |
| 1709 | + |
| 1710 | +```js |
| 1711 | +Promise.resolve().then(() => console.log(2)); |
| 1712 | +queueMicrotask(() => console.log(3)); |
| 1713 | +process.nextTick(() => console.log(1)); |
| 1714 | +// Output: |
| 1715 | +// 1 |
| 1716 | +// 2 |
| 1717 | +// 3 |
| 1718 | +``` |
| 1719 | + |
| 1720 | +For *most* userland use cases, the `queueMicrotask()` API provides a portable |
| 1721 | +and reliable mechanism for deferring execution that works across multiple |
| 1722 | +JavaScript platform environments and should be favored over `process.nextTick()`. |
| 1723 | +In simple scenarios, `queueMicrotask()` can be a drop-in replacement for |
| 1724 | +`process.nextTick()`. |
| 1725 | + |
| 1726 | +```js |
| 1727 | +console.log('start'); |
| 1728 | +queueMicrotask(() => { |
| 1729 | + console.log('microtask callback'); |
| 1730 | +}); |
| 1731 | +console.log('scheduled'); |
| 1732 | +// Output: |
| 1733 | +// start |
| 1734 | +// scheduled |
| 1735 | +// microtask callback |
| 1736 | +``` |
| 1737 | + |
| 1738 | +One note-worthy difference between the two APIs is that `process.nextTick()` |
| 1739 | +allows specifying additional values that will be passed as arguments to the |
| 1740 | +deferred function when it is called. Achieving the same result with |
| 1741 | +`queueMicrotask()` requires using either a closure or a bound function: |
| 1742 | + |
| 1743 | +```js |
| 1744 | +function deferred(a, b) { |
| 1745 | + console.log('microtask', a + b); |
| 1746 | +} |
| 1747 | + |
| 1748 | +console.log('start'); |
| 1749 | +queueMicrotask(deferred.bind(undefined, 1, 2)); |
| 1750 | +console.log('scheduled'); |
| 1751 | +// Output: |
| 1752 | +// start |
| 1753 | +// scheduled |
| 1754 | +// microtask 3 |
| 1755 | +``` |
| 1756 | + |
| 1757 | +There are minor differences in the way errors raised from within the next tick |
| 1758 | +queue and microtask queue are handled. Errors thrown within a queued microtask |
| 1759 | +callback should be handled within the queued callback when possible. If they are |
| 1760 | +not, the `process.on('uncaughtException')` event handler can be used to capture |
| 1761 | +and handle the errors. |
| 1762 | + |
| 1763 | +When in doubt, unless the specific capabilities of `process.nextTick()` are |
| 1764 | +needed, use `queueMicrotask()`. |
| 1765 | + |
1702 | 1766 | ## `process.noDeprecation` |
1703 | 1767 | <!-- YAML |
1704 | 1768 | added: v0.8.0 |
@@ -2671,6 +2735,7 @@ cases: |
2671 | 2735 | [`process.kill()`]: #process_process_kill_pid_signal |
2672 | 2736 | [`process.setUncaughtExceptionCaptureCallback()`]: process.md#process_process_setuncaughtexceptioncapturecallback_fn |
2673 | 2737 | [`promise.catch()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/catch |
| 2738 | +[`queueMicrotask()`]: globals.md#globals_queuemicrotask_callback |
2674 | 2739 | [`readable.read()`]: stream.md#stream_readable_read_size |
2675 | 2740 | [`require()`]: globals.md#globals_require |
2676 | 2741 | [`require.main`]: modules.md#modules_accessing_the_main_module |
|