Skip to content

Commit

Permalink
Update enqueue promise jobs description
Browse files Browse the repository at this point in the history
I found the enqueue promise jobs description hard to digest with several names and concepts referenced.

I tried to make it more clear.
  • Loading branch information
andimarek authored Dec 17, 2024
1 parent a107730 commit 0503f9c
Showing 1 changed file with 18 additions and 17 deletions.
35 changes: 18 additions & 17 deletions src/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -217,26 +217,27 @@ class DataLoader<K, V, C = K> {
// after the current execution context has completed:
// http://www.ecma-international.org/ecma-262/6.0/#sec-jobs-and-job-queues
//
// Node.js uses the `process.nextTick` mechanism to implement the concept of a
// Job, maintaining a global FIFO JobQueue for all Jobs, which is flushed after
// the current call stack ends.
//
// When calling `then` on a Promise, it enqueues a Job on a specific
// "PromiseJobs" JobQueue which is flushed in Node as a single Job on the
// global JobQueue.
//
// DataLoader batches all loads which occur in a single frame of execution, but
// should include in the batch all loads which occur during the flushing of the
// "PromiseJobs" JobQueue after that same execution frame.
// "PromiseJobs" JobQueue which is flushed "recursively" until it

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Trailing spaces not allowed

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Delete `·`

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Trailing spaces not allowed

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Delete `·`

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Trailing spaces not allowed

Check failure on line 221 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Delete `·`
// is empty, including new Promise Jobs that are added during the current

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Trailing spaces not allowed

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Delete `·`

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Trailing spaces not allowed

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Delete `·`

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Trailing spaces not allowed

Check failure on line 222 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Delete `·`
// flushing.
//
// In order to avoid the DataLoader dispatch Job occuring before "PromiseJobs",
// A Promise Job is created with the sole purpose of enqueuing a global Job,
// ensuring that it always occurs after "PromiseJobs" ends.
// DataLoader batches all loads which occur in a single frame of execution
// (synchronously executed code), but should include in the batch all loads

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Trailing spaces not allowed

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Delete `·`

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Trailing spaces not allowed

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Delete `·`

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Trailing spaces not allowed

Check failure on line 226 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Delete `·`
// which occur during the flushing of the "PromiseJobs" JobQueue after that

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Trailing spaces not allowed

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Delete `·`

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Trailing spaces not allowed

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Delete `·`

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Trailing spaces not allowed

Check failure on line 227 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Delete `·`
// same execution frame.
//

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Trailing spaces not allowed

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 18

Delete `·`

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Trailing spaces not allowed

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 20

Delete `·`

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Trailing spaces not allowed

Check failure on line 229 in src/index.js

View workflow job for this annotation

GitHub Actions / Testing on Node 22

Delete `·`
// In Node.js we can use `process.nextTick` that is run
// immediately after the "PromiseJobs" is empty.
//
// Browsers do not have an equivalent mechanism, therfore
// we use `setImmediate` or `setTimeout` which is always run after all Promise
// jobs. This might be less efficient that `nextTick`, which is ensured to
// run directly after the all Promise jobs are done.
//
// Node.js's job queue is unique. Browsers do not have an equivalent mechanism
// for enqueuing a job to be performed after promise microtasks and before the
// next macrotask. For browser environments, a macrotask is used (via
// setImmediate or setTimeout) at a potential performance penalty.
// In either environment we wrap `nextTick`, `setImmedidate` or `setTimeout`
// in a Promise handler itself, to ensure the flushing of "PromiseJobs" has
// started.
const enqueuePostPromiseJob =
typeof process === 'object' && typeof process.nextTick === 'function'
? function (fn) {
Expand Down

0 comments on commit 0503f9c

Please sign in to comment.