Repository navigation
01. The async cycle
######RATIONALE
Because JavaScript is single-threaded and works on a loop-stack, you can be assured that if you have control, then control is not relinquished until you have ended your stream of commands.
The problem with async functionality is that you can not predict when all of the competing requests will be served. While it is attractive to do this entire process synchronously, this would impede the efficiency of the process because
- async downloads can occur in the background simultaneously, hence more efficiently; and
- while the fetching is completing, off-process events can be completed (like page layouts).
The problem then becomes ensuring that control is handed over to a process only when it has all of its requirements prefetched. This gives the impression that the code is requiring modules synchronously, but in reality some or all of a module's requirements will have been simply downloaded already and registered to be reused and others downloaded just prior to the code being executed.
An important corollary of this rationale is that your code may have small delays while new requirements are prefetched and that you should structure your process control with hand-overs between modules rather than just loading modules haphazardly.
######PREFETCHING QUEUE
Prefetching is just getting a dependency so that when the module seeks to fetch it with require(id), then it is already there to use. Module dependencies that are created from require(id) are called requirements.
Prefetching gives the illusion of synchronicity at the point of module execution. The mechanism works on a simple queue that is expanded as new requirements are added and contracted as the registrations of requirements are completed.
When the queue reaches nil length, then control is handed to the original module that had been requested.
If there are multiple modules being executed simultaneously, then all of them will have to wait until the requirements for all of them have been fetched because there is only 1 queue. Having a single queue simplifies control and reduces the possibility of errors.
As long as you start the process with just 1 module, no matter how many sub-modules you call, the process will always return efficiently (as long as the required modules can be found).
You should not make multiple simultaneous calls to NodalRequire.requireAsync because this can currently handle just 1 callback and 1 original module at any one time. The first call to it should complete before making subsequent calls.
######PREFETCHING MECHANISM
The mechanism works by starting with the original module 0:
- resolve the canonical address for module n
- request the content from that address,
- store the text for module n as a definition,
- search that text for any
require(id)patterns, - extract them and add them to the queue,
- remove module n from the queue,
- ask the queue to check itself,
- if there is nothing queued, then initialise module 0,
- otherwise await other content downloads.
This means that every module definition that is downloaded is searched and its requirements are added to the queue before the queue is asked to check itself.
Hence, all of the dependencies of the module chain are fetched before even the original module is initialised.
Importantly, modules are initialised when first required in an executed module, and NOT when they are fetched. This behaviour saves memory, but is also more consistent with Node.js.