/usr/share/doc/libjs-mathjax-doc/html/advanced/queues.html is in libjs-mathjax-doc 2.7+20171212-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 | <!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Using Queues — MathJax 2.7 documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="index" title="Index"
href="../genindex.html"/>
<link rel="search" title="Search" href="../search.html"/>
<link rel="top" title="MathJax 2.7 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"/>
<script src="../_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="../index.html" class="icon icon-home"> MathJax
</a>
<div class="version">
2.7
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Basic Usage</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../mathjax.html">What is MathJax?</a></li>
<li class="toctree-l1"><a class="reference internal" href="../start.html">Getting Started with MathJax</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation.html">Installing and Testing MathJax</a></li>
<li class="toctree-l1"><a class="reference internal" href="../configuration.html">Loading and Configuring MathJax</a></li>
<li class="toctree-l1"><a class="reference internal" href="../config-files.html">Combined MathJax Configurations</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../tex.html">MathJax TeX and LaTeX Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../mathml.html">MathJax MathML Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../asciimath.html">MathJax AsciiMath Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../output.html">MathJax Output Formats</a></li>
<li class="toctree-l1"><a class="reference internal" href="../font-support.html">MathJax Font Support</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../localization.html">MathJax Localization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../safe-mode.html">MathJax Safe-mode</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../community.html">The MathJax Community</a></li>
</ul>
<p class="caption"><span class="caption-text">Configuration options</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../options/index.html">Configuration options</a></li>
</ul>
<p class="caption"><span class="caption-text">Advanced topics</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="model.html">The MathJax Processing Model</a></li>
<li class="toctree-l1"><a class="reference internal" href="startup.html">The MathJax Startup Sequence</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="synchronize.html">Synchronizing Your Code with MathJax</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="callbacks.html">Using Callbacks</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Using Queues</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#constructing-queues">Constructing Queues</a></li>
<li class="toctree-l3"><a class="reference internal" href="#callbacks-versus-callback-specifications">Callbacks versus Callback Specifications</a></li>
<li class="toctree-l3"><a class="reference internal" href="#the-mathjax-processing-queue">The MathJax Processing Queue</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="signals.html">Using Signals</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="dynamic.html">Loading MathJax Dynamically</a></li>
<li class="toctree-l1"><a class="reference internal" href="typeset.html">Modifying Math on the Page</a></li>
<li class="toctree-l1"><a class="reference internal" href="toMathML.html">Obtaining the MathML for an Expression</a></li>
<li class="toctree-l1"><a class="reference internal" href="extension-writing.html">Writing MathJax Extensions</a></li>
<li class="toctree-l1"><a class="reference internal" href="debugging-tips.html">Debugging Tips</a></li>
<li class="toctree-l1"><a class="reference internal" href="mathjax-node.html">MathJax on NodeJS</a></li>
</ul>
<p class="caption"><span class="caption-text">The MathJax API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../api/index.html">Details of the MathJax API</a></li>
</ul>
<p class="caption"><span class="caption-text">Miscellanea</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../misc/accessibility-features.html">Accessibility features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/browser-compatibility.html">Browser Compatibility</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/epub.html">EPUB3 Reading Systems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/badges.html">MathJax Badges and Logo</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/articles.html">Articles and Presentations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/platforms.html">Using MathJax in Web Platforms</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/faq.html">MathJax FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../misc/mathjax-in-use.html">MathJax in Use</a></li>
</ul>
<p class="caption"><span class="caption-text">Upgrading MathJax</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../upgrading/index.html">Upgrading MathJax</a></li>
</ul>
<p class="caption"><span class="caption-text">Reference Pages</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/HTML-snippets.html">HTML snippets</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/CSS-styles.html">CSS style objects</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/localization-strings.html">Localization strings</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">MathJax</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> »</li>
<li><a href="synchronize.html">Synchronizing your code with MathJax</a> »</li>
<li>Using Queues</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/advanced/queues.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<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’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
<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’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 <code class="xref py py-meth docutils literal"><span class="pre">MathJax.Callback.Queue()</span></code> 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"><span class="std std-ref">Using Callbacks</span></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 <code class="xref py py-meth docutils literal"><span class="pre">MathJax.Callback.Queue()</span></code>, 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></span><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 <code class="docutils literal"><span class="pre">f</span></code> 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 <code class="docutils literal"><span class="pre">f</span></code> is not a function that operates
asynchronously, so it would have been easier to just call <code class="docutils literal"><span class="pre">f</span></code> 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></span><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">"Require"</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">"[MathJax]/extensions/AMSmath.js"</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 <code class="docutils literal"><span class="pre">MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js")</span></code>
is queued between two calls to <code class="docutils literal"><span class="pre">f</span></code>. The first call to <code class="docutils literal"><span class="pre">f(1)</span></code> will
be made immediately, then the <code class="xref py py-meth docutils literal"><span class="pre">MathJax.Ajax.Require()</span></code> statement
will be performed. Since the <code class="docutils literal"><span class="pre">Require</span></code> 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
<code class="docutils literal"><span class="pre">f(2)</span></code> will not be made until that callback is performed,
effectively synchronizing the second call to <code class="docutils literal"><span class="pre">f</span></code> with the completion
of the file loading. This is equivalent to</p>
<div class="highlight-javascript"><div class="highlight"><pre><span></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">"[MathJax]/extensions/AMSmath.js"</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 <code class="docutils literal"><span class="pre">Require()</span></code> 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></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="s2">"Require"</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">"[MathJax]/extensions/AMSmath.js"</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">"Require"</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">"[MathJax]/config/local/AMSmathAdditions.js"</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 <code class="docutils literal"><span class="pre">f(1)</span></code> then load the
local AMSmath modifications, and then call <code class="docutils literal"><span class="pre">f(2)</span></code>, 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></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="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">"[MathJax]/extensions/AMSmath.js"</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 <code class="docutils literal"><span class="pre">f</span></code>, the
callback for the file load, and the second call to <code class="docutils literal"><span class="pre">f</span></code>. The queue
performs <code class="docutils literal"><span class="pre">f(1)</span></code>, waits for the file load callback to be called, and
then calls <code class="docutils literal"><span class="pre">f(2)</span></code>. 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 <code class="docutils literal"><span class="pre">f(1)</span></code>, while in the example above, the
file load is guaranteed not to begin until after <code class="docutils literal"><span class="pre">f(1)</span></code> is executed.</p>
<p>As a further example, consider</p>
<div class="highlight-javascript"><div class="highlight"><pre><span></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">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">"[MathJax]/extensions/AMSmath.js"</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">"[MathJax]/config/local/AMSmathAdditions.js"</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 <code class="docutils literal"><span class="pre">["Require",</span>
<span class="pre">MathJax.Ajax,</span> <span class="pre">"[MathJax]/extensions/AMSmath.js"]</span></code> and <code class="docutils literal"><span class="pre">["Require",</span>
<span class="pre">MathJax.Ajax,</span> <span class="pre">"[MathJax]/config/local/AMSmathAdditions.js"]</span></code> instead. In that
example, <code class="docutils literal"><span class="pre">AMSmath.js</span></code> is loaded, then <code class="docutils literal"><span class="pre">f(1)</span></code> is called, then the
local additions are loaded, then <code class="docutils literal"><span class="pre">f(2)</span></code> 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 <code class="docutils literal"><span class="pre">f(1)</span></code> is guaranteed not to be performed until
after the AMSmath extensions load, and <code class="docutils literal"><span class="pre">f(2)</span></code> 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></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">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">"file1.js"</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">"file2.js"</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">"file3.js"</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">"file4.js"</span><span class="p">),</span>
<span class="p">[</span><span class="nx">f</span><span class="p">,</span> <span class="s2">"all done"</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 <code class="docutils literal"><span class="pre">f("all</span> <span class="pre">done")</span></code>. 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 <code class="docutils literal"><span class="pre">MathJax.Hub.queue</span></code> 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
available.</p>
<p>As a result, any call to <code class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Typeset()</span></code> (or
<code class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Process()</span></code>, or <code class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Update()</span></code>, 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.</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’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’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
<code class="xref py py-meth docutils literal"><span class="pre">MathJax.Hub.Queue()</span></code> command. For example</p>
<div class="highlight-javascript"><div class="highlight"><pre><span></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="s2">"Typeset"</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">"MathDiv"</span><span class="p">]);</span>
</pre></div>
</div>
<p>would queue the command <code class="docutils literal"><span class="pre">MathJax.Hub.Typeset("MathDiv")</span></code>, causing
the contents of the DOM element with <cite>id</cite> equal to <code class="docutils literal"><span class="pre">MathDiv</span></code> 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 <code class="docutils literal"><span class="pre">MathJax.Hub.queue</span></code> so that it won’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></span><span class="p"><</span><span class="nt">script</span> <span class="na">type</span><span class="o">=</span><span class="s">"text/javascript"</span> <span class="na">src</span><span class="o">=</span><span class="s">"/MathJax/MathJax.js"</span><span class="p">></</span><span class="nt">script</span><span class="p">></span>
<span class="p"><</span><span class="nt">script</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="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="p"></</span><span class="nt">script</span><span class="p">></span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="articleComments">
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="signals.html" class="btn btn-neutral float-right" title="Using Signals" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="callbacks.html" class="btn btn-neutral" title="Using Callbacks" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2017 The MathJax Consortium.
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'../',
VERSION:'2.7',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</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>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
</body>
</html>
|