scratch/output/Scratch/js/MathJax/docs/html/queues.html
2010-08-16 12:02:28 +02:00

334 lines
No EOL
25 KiB
HTML

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Using Queues &mdash; MathJax v1.0 documentation</title>
<link rel="stylesheet" href="_static/mj.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="top" title="MathJax v1.0 documentation" href="index.html" />
<link rel="up" title="Synchronizing your code with MathJax" href="synchronize.html" />
<link rel="next" title="Using Signals" href="signals.html" />
<link rel="prev" title="Using Callbacks" href="callbacks.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="signals.html" title="Using Signals"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="callbacks.html" title="Using Callbacks"
accesskey="P">previous</a> |</li>
<li><a href="index.html">MathJax v1.0 documentation</a> &raquo;</li>
<li><a href="synchronize.html" accesskey="U">Synchronizing your code with MathJax</a> &raquo;</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="using-queues">
<span id="id1"></span><h1>Using Queues<a class="headerlink" href="#using-queues" title="Permalink to this headline"></a></h1>
<p>The <cite>callback queue</cite> is one of MathJax&#8217;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
asynchornously, MathJax needs a way to coordinate those actions so
that they occur in the right order. The
<cite>MathJax.Callback.Queue</cite> object provides that mechanism.</p>
<p>A <cite>callback queue</cite> 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
<cite>Callback</cite> 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&#8217;t get performed until other
ones are known to be finished, even if those commands usually operate
asynchronously.</p>
<div class="section" id="constructing-queues">
<h2>Constructing Queues<a class="headerlink" href="#constructing-queues" title="Permalink to this headline"></a></h2>
<p>A queue is created via the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Callback.Queue()</span></tt> command,
which returns a <cite>MathJax.Callback.Queue</cite> object. The queue
itself consists of a series of commands given as callback
specifications (see <a class="reference internal" href="callbacks.html#using-callbacks"><em>Using Callbacks</em></a> 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 <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Callback.Queue()</span></tt>, or you can create an
empty queue to which commands are added later. Once a
<cite>MathJax.Callback.Queue</cite> 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.</p>
<p>For example,</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">function</span> <span class="nx">f</span><span class="p">(</span><span class="nx">x</span><span class="p">)</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="nx">x</span><span class="p">)}</span>
<span class="kd">var</span> <span class="nx">queue</span> <span class="o">=</span> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">([</span><span class="nx">f</span><span class="p">,</span> <span class="mi">15</span><span class="p">],</span> <span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">10</span><span class="p">],</span> <span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">5</span><span class="p">]);</span>
<span class="nx">queue</span><span class="p">.</span><span class="nx">Push</span><span class="p">([</span><span class="nx">f</span><span class="p">,</span> <span class="mi">0</span><span class="p">]);</span>
</pre></div>
</div>
<p>would create a queue containing three commands, each calling the
function <tt class="docutils literal"><span class="pre">f</span></tt> 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 <tt class="docutils literal"><span class="pre">f</span></tt> is not a function that operates
asynchronously, so it would have been easier to just call <tt class="docutils literal"><span class="pre">f</span></tt> four
times directly. The power of the queue comes from calling commands
that could operate asynchronously. For example:</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="kd">function</span> <span class="nx">f</span><span class="p">(</span><span class="nx">x</span><span class="p">)</span> <span class="p">{</span><span class="nx">alert</span><span class="p">(</span><span class="nx">x</span><span class="p">)}</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span>
<span class="p">[</span><span class="s2">&quot;Require&quot;</span><span class="p">,</span> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">,</span> <span class="s2">&quot;[MathJax]/extensions/AMSmath.js&quot;</span><span class="p">],</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="p">);</span>
</pre></div>
</div>
<p>Here, the command <tt class="docutils literal"><span class="pre">MathJax.Ajax.require(&quot;extensions/AMSmath.js&quot;)</span></tt> is
queued between two calls to <tt class="docutils literal"><span class="pre">f</span></tt>. The first call to <tt class="docutils literal"><span class="pre">f(1)</span></tt> will be
made immediately, then the <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></tt> statement will
be performed. Since the <tt class="docutils literal"><span class="pre">Require</span></tt> method loads a file, it operates
asynchronously, and its return value is a <cite>MathJax.Callback</cite>
object that will be called when the file is loaded. The call to
<tt class="docutils literal"><span class="pre">f(2)</span></tt> will not be made until that callback is performed,
effectively synchronizing the second call to <tt class="docutils literal"><span class="pre">f</span></tt> with the completion
of the file loading. This is equivalent to</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">f</span><span class="p">(</span><span class="mi">1</span><span class="p">);</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;[MathJax]/extensions/AMSmath.js&quot;</span><span class="p">,</span> <span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">]);</span>
</pre></div>
</div>
<p>since the <tt class="docutils literal"><span class="pre">Require()</span></tt> 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.</p>
<p>For example,</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span>
<span class="p">[</span><span class="s2">&quot;Require&quot;</span><span class="p">,</span> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">,</span> <span class="s2">&quot;[MathJax]/extensions/AMSmath.js&quot;</span><span class="p">],</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span>
<span class="p">[</span><span class="s2">&quot;Require&quot;</span><span class="p">,</span> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">,</span> <span class="s2">&quot;[MathJax]/config/local/AMSmathAdditions.js&quot;</span><span class="p">],</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="p">);</span>
</pre></div>
</div>
<p>would load the AMSmath extension, then call <tt class="docutils literal"><span class="pre">f(1)</span></tt> then load the
local AMSmath modifications, and then call <tt class="docutils literal"><span class="pre">f(2)</span></tt>, with each action
waiting for the previous one to complete before being performed
itself.</p>
</div>
<div class="section" id="callbacks-versus-callback-specifications">
<h2>Callbacks versus Callback Specifications<a class="headerlink" href="#callbacks-versus-callback-specifications" title="Permalink to this headline"></a></h2>
<p>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,</p>
<div class="highlight-javascript"><div class="highlight"><pre> <span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;[MathJax]/extensions/AMSmath.js&quot;</span><span class="p">),</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">],</span>
<span class="p">);</span>
</pre></div>
</div>
<p>starts the loading of the AMSmath extension before the queue is
created, and then creates the queue containing the call to <tt class="docutils literal"><span class="pre">f</span></tt>, the
callback for the file load, and the second call to <tt class="docutils literal"><span class="pre">f</span></tt>. The queue
performs <tt class="docutils literal"><span class="pre">f(1)</span></tt>, waits for the file load callback to be called, and
then calls <tt class="docutils literal"><span class="pre">f(2)</span></tt>. 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 <tt class="docutils literal"><span class="pre">f(1)</span></tt>, while in the example above, the
file load is guaranteed not to begin until after <tt class="docutils literal"><span class="pre">f(1)</span></tt> is executed.</p>
<p>As a further example, consider</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;[MathJax]/extensions/AMSmath.js&quot;</span><span class="p">),</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">1</span><span class="p">],</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;[MathJax]/config/local/AMSmathAdditions.js&quot;</span><span class="p">),</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="mi">2</span><span class="p">]</span>
<span class="p">);</span>
</pre></div>
</div>
<p>in comparison to the example above that uses <tt class="docutils literal"><span class="pre">[&quot;Require&quot;,</span>
<span class="pre">MathJax.Ajax,</span> <span class="pre">&quot;[MathJax]/extensions/AMSmath.js&quot;]</span></tt> and <tt class="docutils literal"><span class="pre">[&quot;Require&quot;,</span>
<span class="pre">MathJax.Ajax,</span> <span class="pre">&quot;[MathJax]/config/local/AMSmathAdditions.js&quot;]</span></tt> instead. In that
example, <tt class="docutils literal"><span class="pre">AMSmath.js</span></tt> is loaded, then <tt class="docutils literal"><span class="pre">f(1)</span></tt> is called, then the
local additions are loaded, then <tt class="docutils literal"><span class="pre">f(2)</span></tt> is called.</p>
<p>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 <strong>not</strong> to happen in the other example.
Note, however, that <tt class="docutils literal"><span class="pre">f(1)</span></tt> is guaranteed not to be performed until
after the AMSmath extensions load, and <tt class="docutils literal"><span class="pre">f(2)</span></tt> will not occur until
after both files are loaded.</p>
<p>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,</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Callback</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;file1.js&quot;</span><span class="p">),</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;file2.js&quot;</span><span class="p">),</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;file3.js&quot;</span><span class="p">),</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Ajax</span><span class="p">.</span><span class="nx">Require</span><span class="p">(</span><span class="s2">&quot;file4.js&quot;</span><span class="p">),</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="s2">&quot;all done&quot;</span><span class="p">]</span>
<span class="p">);</span>
</pre></div>
</div>
<p>starts four files loading all at once, and waits for all four to
complete before calling <tt class="docutils literal"><span class="pre">f(&quot;all</span> <span class="pre">done&quot;)</span></tt>. The order in which they
complete is immaterial, and they all are being requested
simultaneously.</p>
</div>
<div class="section" id="the-mathjax-processing-queue">
<h2>The MathJax Processing Queue<a class="headerlink" href="#the-mathjax-processing-queue" title="Permalink to this headline"></a></h2>
<p>MathJax uses a queue stored as <tt class="docutils literal"><span class="pre">MathJax.Hub.queue</span></tt> 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.</p>
<p>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
evailable.</p>
<p>As a result, any call to <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Typeset()</span></tt> (or
<tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Process()</span></tt>, or <tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Update()</span></tt>, 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 relys 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.</p>
<p>Furthermore, your own typesetting calls may need to wait for file loading
to occur that is already underway, so even if you don&#8217;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
<em>previous</em> 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&#8217;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.</p>
<p>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.</p>
<p>To place an action in the MathJax queue, use the
<tt class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Queue()</span></tt> command. For example</p>
<div class="highlight-javascript"><div class="highlight"><pre><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">.</span><span class="nx">Queue</span><span class="p">([</span><span class="s2">&quot;Typeset&quot;</span><span class="p">,</span><span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">,</span><span class="s2">&quot;MathDiv&quot;</span><span class="p">]);</span>
</pre></div>
</div>
<p>would queue the command <tt class="docutils literal"><span class="pre">MathJax.Hub.Typeset(&quot;MathDiv&quot;)</span></tt>, causing
the contents of the DOM element with <cite>id</cite> equal to <tt class="docutils literal"><span class="pre">MathDiv</span></tt> to be
typeset.</p>
<p>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 <tt class="docutils literal"><span class="pre">MathJax.Hub.queue</span></tt> so that it won&#8217;t be performed until MathJax
finishes everything it has queued when it was loaded. For example,</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt">&lt;script </span><span class="na">type=</span><span class="s">&quot;text/javascript&quot;</span> <span class="na">src=</span><span class="s">&quot;/MathJax/MathJax.js&quot;</span><span class="nt">&gt;&lt;/script&gt;</span>
<span class="nt">&lt;script&gt;</span>
<span class="nx">MathJax</span><span class="p">.</span><span class="nx">Hub</span><span class="p">.</span><span class="nx">Queue</span><span class="p">(</span><span class="kd">function</span> <span class="p">()</span> <span class="p">{</span>
<span class="c1">// ... your startup commands here ...</span>
<span class="p">});</span>
<span class="nt">&lt;/script&gt;</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Using Queues</a><ul>
<li><a class="reference internal" href="#constructing-queues">Constructing Queues</a></li>
<li><a class="reference internal" href="#callbacks-versus-callback-specifications">Callbacks versus Callback Specifications</a></li>
<li><a class="reference internal" href="#the-mathjax-processing-queue">The MathJax Processing Queue</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="callbacks.html"
title="previous chapter">Using Callbacks</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="signals.html"
title="next chapter">Using Signals</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/queues.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="signals.html" title="Using Signals"
>next</a> |</li>
<li class="right" >
<a href="callbacks.html" title="Using Callbacks"
>previous</a> |</li>
<li><a href="index.html">MathJax v1.0 documentation</a> &raquo;</li>
<li><a href="synchronize.html" >Synchronizing your code with MathJax</a> &raquo;</li>
</ul>
</div>
<div class="footer">
&copy; Copyright 2010 Design Science.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0b2.
</div>
</body>
</html>