Skip to content

Commit 0503f9c

Browse files
authored
Update enqueue promise jobs description
I found the enqueue promise jobs description hard to digest with several names and concepts referenced. I tried to make it more clear.
1 parent a107730 commit 0503f9c

File tree

1 file changed

+18
-17
lines changed

1 file changed

+18
-17
lines changed

src/index.js

+18-17
Original file line numberDiff line numberDiff line change
@@ -217,26 +217,27 @@ class DataLoader<K, V, C = K> {
217217
// after the current execution context has completed:
218218
// http://www.ecma-international.org/ecma-262/6.0/#sec-jobs-and-job-queues
219219
//
220-
// Node.js uses the `process.nextTick` mechanism to implement the concept of a
221-
// Job, maintaining a global FIFO JobQueue for all Jobs, which is flushed after
222-
// the current call stack ends.
223-
//
224220
// When calling `then` on a Promise, it enqueues a Job on a specific
225-
// "PromiseJobs" JobQueue which is flushed in Node as a single Job on the
226-
// global JobQueue.
227-
//
228-
// DataLoader batches all loads which occur in a single frame of execution, but
229-
// should include in the batch all loads which occur during the flushing of the
230-
// "PromiseJobs" JobQueue after that same execution frame.
221+
// "PromiseJobs" JobQueue which is flushed "recursively" until it
222+
// is empty, including new Promise Jobs that are added during the current
223+
// flushing.
231224
//
232-
// In order to avoid the DataLoader dispatch Job occuring before "PromiseJobs",
233-
// A Promise Job is created with the sole purpose of enqueuing a global Job,
234-
// ensuring that it always occurs after "PromiseJobs" ends.
225+
// DataLoader batches all loads which occur in a single frame of execution
226+
// (synchronously executed code), but should include in the batch all loads
227+
// which occur during the flushing of the "PromiseJobs" JobQueue after that
228+
// same execution frame.
229+
//
230+
// In Node.js we can use `process.nextTick` that is run
231+
// immediately after the "PromiseJobs" is empty.
232+
//
233+
// Browsers do not have an equivalent mechanism, therfore
234+
// we use `setImmediate` or `setTimeout` which is always run after all Promise
235+
// jobs. This might be less efficient that `nextTick`, which is ensured to
236+
// run directly after the all Promise jobs are done.
235237
//
236-
// Node.js's job queue is unique. Browsers do not have an equivalent mechanism
237-
// for enqueuing a job to be performed after promise microtasks and before the
238-
// next macrotask. For browser environments, a macrotask is used (via
239-
// setImmediate or setTimeout) at a potential performance penalty.
238+
// In either environment we wrap `nextTick`, `setImmedidate` or `setTimeout`
239+
// in a Promise handler itself, to ensure the flushing of "PromiseJobs" has
240+
// started.
240241
const enqueuePostPromiseJob =
241242
typeof process === 'object' && typeof process.nextTick === 'function'
242243
? function (fn) {

0 commit comments

Comments
 (0)