Using Queues

The callback queue is one of MathJax’s main tools for synchronizing its actions, both internally, and with external programs, like javascript code that you may write as part of dynamic web pages. Because many actions in MathJax (like loading files) operate asynchronously, MathJax needs a way to coordinate those actions so that they occur in the right order. The MathJax.Callback.Queue object provides that mechanism.

A callback queue is a list of commands that will be performed one at a time, in order. If the return value of one of the commands is a Callback object, processing is suspended until that callback is called, and then processing of the commands is resumed. In this way, if a command starts an asynchronous operation like loading a file, it can return the callback for that file-load operation and the queue will wait until the file has loaded before continuing. Thus a queue can be used to guarantee that commands don’t get performed until other ones are known to be finished, even if those commands usually operate asynchronously.

Constructing Queues

A queue is created via the MathJax.Callback.Queue() command, which returns a MathJax.Callback.Queue object. The queue itself consists of a series of commands given as callback specifications (see Using Callbacks for details on callbacks), which allow you to provide functions (together with their arguments) to be executed. You can provide the collection of callback specifications when the queue is created by passing them as arguments to MathJax.Callback.Queue(), or you can create an empty queue to which commands are added later. Once a MathJax.Callback.Queue object is created, you can push additional callbacks on the end of the queue; if the queue is empty, the command will be performed immediately, while if the queue is waiting for another command to complete, the new command will be queued for later processing.

For example,

function f(x) {alert(x)}
var queue = MathJax.Callback.Queue([f, 15], [f, 10], [f, 5]);
queue.Push([f, 0]);

would create a queue containing three commands, each calling the function f with a different input, that are performed in order. A fourth command is then added to the queue, to be performed after the other three. In this case, the result will be four alerts, the first with the number 15, the second with 10, the third with 5 and the fourth with 0. Of course f is not a function that operates asynchronously, so it would have been easier to just call f four times directly. The power of the queue comes from calling commands that could operate asynchronously. For example:

function f(x) {alert(x)}
MathJax.Callback.Queue(
  [f, 1],
  ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"],
  [f, 2]
);

Here, the command MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js") is queued between two calls to f. The first call to f(1) will be made immediately, then the MathJax.Ajax.Require() statement will be performed. Since the Require method loads a file, it operates asynchronously, and its return value is a MathJax.Callback object that will be called when the file is loaded. The call to f(2) will not be made until that callback is performed, effectively synchronizing the second call to f with the completion of the file loading. This is equivalent to

f(1);
MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js", [f, 2]);

since the Require() command allows you to specify a (single) callback to be performed on the completion of the file load. Note, however, that the queue could be used to synchronize several file loads along with multiple function calls, so is more flexible.

For example,

MathJax.Callback.Queue(
  ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"],
  [f, 1],
  ["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"],
  [f, 2]
);

would load the AMSmath extension, then call f(1) then load the local AMSmath modifications, and then call f(2), with each action waiting for the previous one to complete before being performed itself.

Callbacks versus Callback Specifications

If one of the callback specifications is an actual callback object itself, then the queue will wait for that action to be performed before proceeding. For example,

 MathJax.Callback.Queue(
     [f, 1],
     MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"),
     [f, 2],
);

starts the loading of the AMSmath extension before the queue is created, and then creates the queue containing the call to f, the callback for the file load, and the second call to f. The queue performs f(1), waits for the file load callback to be called, and then calls f(2). The difference between this and the second example above is that, in this example the file load is started before the queue is even created, so the file is potentially loaded and executed before the call to f(1), while in the example above, the file load is guaranteed not to begin until after f(1) is executed.

As a further example, consider

MathJax.Callback.Queue(
  MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"),
  [f, 1],
  MathJax.Ajax.Require("[MathJax]/config/local/AMSmathAdditions.js"),
  [f, 2]
);

in comparison to the example above that uses ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"] and ["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"] instead. In that example, AMSmath.js is loaded, then f(1) is called, then the local additions are loaded, then f(2) is called.

Here, however, both file loads are started before the queue is created, and are operating in parallel (rather than sequentially as in the earlier example). It is possible for the loading of the local additions to complete before the AMSmath extension is loaded in this case, which was guaranteed not to happen in the other example. Note, however, that f(1) is guaranteed not to be performed until after the AMSmath extensions load, and f(2) will not occur until after both files are loaded.

In this way, it is possible to start asynchronous loading of several files simultaneously, and wait until all of them are loaded (in whatever order) to perform some command. For instance,

MathJax.Callback.Queue(
    MathJax.Ajax.Require("file1.js"),
    MathJax.Ajax.Require("file2.js"),
    MathJax.Ajax.Require("file3.js"),
    MathJax.Ajax.Require("file4.js"),
    [f, "all done"]
);

starts four files loading all at once, and waits for all four to complete before calling f("all done"). The order in which they complete is immaterial, and they all are being requested simultaneously.

The MathJax Processing Queue

MathJax uses a queue stored as MathJax.Hub.queue to regulate its own actions so that they operate in the right order even when some of them include asynchronous operations. You can take advantage of that queue when you make calls to MathJax methods that need to be synchronized with the other actions taken by MathJax. It may not always be apparent, however, which methods fall into that category.

The main source of asynchronous actions in MathJax is the loading of external files, so any action that may cause a file to be loaded may act asynchronously. Many important actions do so, including some that you might not expect; e.g., typesetting mathematics can cause files to be loaded. This is because some TeX commands, for example, are rare enough that they are not included in the core TeX input processor, but instead are defined in extensions that are loaded automatically when needed. The typesetting of an expression containing one of these TeX commands can cause the typesetting process to be suspended while the file is loaded, and then restarted when the extension has become available.

As a result, any call to MathJax.Hub.Typeset() (or MathJax.Hub.Process(), or MathJax.Hub.Update(), etc.) could return long before the mathematics is actually typeset, and the rest of your code may run before the mathematics is available. If you have code that relies on the mathematics being visible on screen, you will need to break that out into a separate operation that is synchronized with the typesetting via the MathJax queue.

Furthermore, your own typesetting calls may need to wait for file loading to occur that is already underway, so even if you don’t need to access the mathematics after it is typeset, you may still need to queue the typeset command in order to make sure it is properly synchronized with previous typeset calls. For instance, if an earlier call started loading an extension and you start another typeset call before that extension is fully loaded, MathJax’s internal state may be in flux, and it may not be prepared to handle another typeset operation yet. This is even more important if you are using other libraries that may call MathJax, in which case your code may not be aware of the state that MathJax is in.

For these reasons, it is always best to perform typesetting operations through the MathJax queue, and the same goes for any other action that could cause files to load. A good rule of thumb is that, if a MathJax function includes a callback argument, that function may operate asynchronously; you should use the MathJax queue to perform it and any actions that rely on its results.

To place an action in the MathJax queue, use the MathJax.Hub.Queue() command. For example

MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);

would queue the command MathJax.Hub.Typeset("MathDiv"), causing the contents of the DOM element with id equal to MathDiv to be typeset.

One of the uses of the MathJax queue is to allow you to synchronize an action with the startup process for MathJax. If you want to have a function performed after MathJax has become completely set up (and performed its initial typesetting of the page), you can push it onto the MathJax.Hub.queue so that it won’t be performed until MathJax finishes everything it has queued when it was loaded. For example,

<script type="text/javascript" src="/MathJax/MathJax.js"></script>
<script>
  MathJax.Hub.Queue(function () {
    // ... your startup commands here ...
  });
</script>