Tiny multi-level queue library in JavaScript, suitable for managing (lots of inter-dependent) DOMContentLoaded handlers
JavaScript HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
test
LICENSE
README.md
priority-ready-queue.js

README.md

This is a super tiny JavaScript library providing a two-level priority-based queue. It's intended as a hacky/dirty alternative for managing depedency issues between DOMContentLoaded handlers (other than struggling with fully-fledged moduling frameworks). However, it's not tightly coupled to DOMContentLoaded handlers --- the "ready" signal has to be explicitly triggered by the library client. As such, it doesn't require jQuery either.

Usage

Please refer to test/jq_test.html for complete examples.

To queue a handler, call PriorityReadyQueue.enqueue(). The function takes two parameters, the first one being the priority of the handlers, the second being the handler (i.e. callback function). For example:

PriorityReadyQueue.enqueue(10, function(){
	console.log('Handled later');
});
PriorityReadyQueue.enqueue(100, function(){
	console.log('Handled first');
});

To signal readiness and start calling the queued handlers, call PriorityReadyQueue.postReady(). An example using jQuery:

jQuery(document).ready(function(){
	PriorityReadyQueue.postReady();
});

Since postReady() is context insensitive (it doesn't care about this), we can abbreviate the above code snippet to jQuery(document).ready(PriorityReadyQueue.postReady); at the cost of code readability.

Handler Execution Ordering

A handler with a larger priority runs before a handler with a smaller priority. For handlers with the same priority, they are called in the order as how they were enqueue()ed.

Nested Enqueuing

PriorityReadyQueue.enqueue() may be called inside our handlers. If we assign a priority lower than or equal to the currently executing handler's priority, the handler is properly queued. If we assign a higher priority, the handler is immediately executed.

If we enqueue() a handler after all the handlers in the queue have been executed, the new handler is immediately executed.

Implementation Details

  • As postReady() is called, the execution of handlers happens at the next JavaScript event loop tick. This is currently achieved with setTimeout() with a timeout of 1 millisecond.
  • However, the immediately executed handlers as illustrated in "Nested Enqueuing" section above are, well, immediately executed, at this tick.
  • All handlers are called within the same JavaScript event loop tick.
  • Any exception thrown will stop the execution of the whole queue, i.e. handlers of lower priorities will not run; handlers, with the same priority as the exception-throwing one, enqueue()ed after this one, will not run either.
  • The priority value is assumed to be a JavaScript Number and can be floating-point. However, please be advised against using floating-point priority values as the library currently does not take correctly comparing IEEE 754 numbers into consideration.

This library uses Apache License 2.0. Please see LICENSES file for further information.