cdocutils.nodes document q)q}q(U nametypesq}q(Xconstructing queuesqNX using queuesqNX using-queuesqKXthe mathjax processing queueq NX(callbacks versus callback specificationsq NuUsubstitution_defsq }q Uparse_messagesq ]qUcurrent_sourceqNU decorationqNUautofootnote_startqKUnameidsq}q(hUconstructing-queuesqhUid1qhU using-queuesqh Uthe-mathjax-processing-queueqh U(callbacks-versus-callback-specificationsquUchildrenq]q(cdocutils.nodes target q)q}q(U rawsourceqX.. _using-queues:qUparentq hUsourceq!cdocutils.nodes reprunicode q"XP/Data/Code/JavaScript/MathJax/Code/SourceForge/trunk/mathjax/docs/rst/queues.rstq#q$}q%bUtagnameq&Utargetq'U attributesq(}q)(Uidsq*]q+Ubackrefsq,]q-Udupnamesq.]q/Uclassesq0]q1Unamesq2]q3Urefidq4huUlineq5KUdocumentq6hh]q7ubcdocutils.nodes section q8)q9}q:(hUh hh!h$Uexpect_referenced_by_nameq;}q(h.]q?h0]q@h,]qAh*]qB(hheh2]qC(hheuh5Kh6hUexpect_referenced_by_idqD}qEhhsh]qF(cdocutils.nodes title qG)qH}qI(hX Using QueuesqJh h9h!h$h&UtitleqKh(}qL(h.]qMh0]qNh,]qOh*]qPh2]qQuh5Kh6hh]qRcdocutils.nodes Text qSX Using QueuesqTqU}qV(hhJh hHubaubcdocutils.nodes paragraph qW)qX}qY(hXThe `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 asynchornously, MathJax needs a way to coordinate those actions so that they occur in the right order. The `MathJax.Callback.Queue` object provides that mechanism.qZh h9h!h$h&U paragraphq[h(}q\(h.]q]h0]q^h,]q_h*]q`h2]qauh5Kh6hh]qb(hSXThe qcqd}qe(hXThe qfh hXubcdocutils.nodes title_reference qg)qh}qi(hX`callback queue`qjh(}qk(h.]qlh0]qmh,]qnh*]qoh2]qpuh hXh]qqhSXcallback queueqrqs}qt(hUh hhubah&Utitle_referencequubhSX[ 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 asynchornously, MathJax needs a way to coordinate those actions so that they occur in the right order. The qvqw}qx(hX[ 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 asynchornously, MathJax needs a way to coordinate those actions so that they occur in the right order. The qyh hXubhg)qz}q{(hX`MathJax.Callback.Queue`q|h(}q}(h.]q~h0]qh,]qh*]qh2]quh hXh]qhSXMathJax.Callback.Queueqq}q(hUh hzubah&huubhSX object provides that mechanism.qq}q(hX object provides that mechanism.qh hXubeubhW)q}q(hX|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.qh h9h!h$h&h[h(}q(h.]qh0]qh,]qh*]qh2]quh5Kh6hh]q(hSXA qq}q(hXA qh hubhg)q}q(hX`callback queue`qh(}q(h.]qh0]qh,]qh*]qh2]quh hh]qhSXcallback queueqq}q(hUh hubah&huubhSXx 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 qq}q(hXx 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 qh hubhg)q}q(hX `Callback`qh(}q(h.]qh0]qh,]qh*]qh2]quh hh]qhSXCallbackqq}q(hUh hubah&huubhSX 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.qq}q(hX 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.qh hubeubh8)q}q(hUh h9h!h$h&h=h(}q(h.]qh0]qh,]qh*]qhah2]qhauh5Kh6hh]q(hG)q}q(hXConstructing Queuesqh hh!h$h&hKh(}q(h.]qh0]qh,]qh*]qh2]quh5Kh6hh]qhSXConstructing Queuesq΅q}q(hhh hubaubhW)q}q(hXfA queue is created via the :meth:`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 :ref:`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 :meth:`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.qh hh!h$h&h[h(}q(h.]qh0]qh,]qh*]qh2]quh5Kh6hh]q(hSXA queue is created via the qۅq}q(hXA queue is created via the qh hubcsphinx.addnodes pending_xref q)q}q(hX :meth:`MathJax.Callback.Queue()`qh hh&U pending_xrefqh(}q(UreftypeqXmethqU reftargetqXMathJax.Callback.QueueqU refdomainqXpyqh*]qh,]qU refexplicitqh.]qh0]qh2]qUrefdocqUqueuesqUpy:classqNU py:moduleqNuh5Kh]qcdocutils.nodes literal q)q}q(hhh(}q(h.]qh0]q(UxrefqhXpy-methqeh,]qh*]qh2]ruh hh]rhSXMathJax.Callback.Queue()rr}r(hUh hubah&UliteralrubaubhSX command, which returns a rr}r(hX command, which returns a r h hubhg)r }r (hX`MathJax.Callback.Queue`r h(}r (h.]rh0]rh,]rh*]rh2]ruh hh]rhSXMathJax.Callback.Queuerr}r(hUh j ubah&huubhSXa object. The queue itself consists of a series of commands given as callback specifications (see rr}r(hXa object. The queue itself consists of a series of commands given as callback specifications (see rh hubh)r}r(hX(:ref:`Using Callbacks `rh hh&hh(}r(UreftyperXrefr hXusing-callbacksr!U refdomainr"Xstdr#h*]r$h,]r%U refexplicitr&h.]r'h0]r(h2]r)hhuh5Kh]r*cdocutils.nodes emphasis r+)r,}r-(hjh(}r.(h.]r/h0]r0(hj#Xstd-refr1eh,]r2h*]r3h2]r4uh jh]r5hSXUsing Callbacksr6r7}r8(hUh j,ubah&Uemphasisr9ubaubhSX 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 r:r;}r<(hX 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 r=h hubh)r>}r?(hX :meth:`MathJax.Callback.Queue()`r@h hh&hh(}rA(UreftyperBXmethrChXMathJax.Callback.QueuerDU refdomainrEXpyrFh*]rGh,]rHU refexplicitrIh.]rJh0]rKh2]rLhhhNhNuh5Kh]rMh)rN}rO(hj@h(}rP(h.]rQh0]rR(hjFXpy-methrSeh,]rTh*]rUh2]rVuh j>h]rWhSXMathJax.Callback.Queue()rXrY}rZ(hUh jNubah&jubaubhSXN, or you can create an empty queue to which commands are added later. Once a r[r\}r](hXN, or you can create an empty queue to which commands are added later. Once a r^h hubhg)r_}r`(hX`MathJax.Callback.Queue`rah(}rb(h.]rch0]rdh,]reh*]rfh2]rguh hh]rhhSXMathJax.Callback.Queuerirj}rk(hUh j_ubah&huubhSX 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.rlrm}rn(hX 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.roh hubeubhW)rp}rq(hX For example,rrh hh!h$h&h[h(}rs(h.]rth0]ruh,]rvh*]rwh2]rxuh5K-h6hh]ryhSX For example,rzr{}r|(hjrh jpubaubcdocutils.nodes literal_block r})r~}r(hXjfunction f(x) {alert(x)} var queue = MathJax.Callback.Queue([f, 15], [f, 10], [f, 5]); queue.Push([f, 0]);rh hh!h$h&U literal_blockrh(}r(UlinenosrUlanguagerX javascriptrU xml:spacerUpreserverh*]rh,]rh.]rh0]rh2]ruh5K4h6hh]rhSXjfunction f(x) {alert(x)} var queue = MathJax.Callback.Queue([f, 15], [f, 10], [f, 5]); queue.Push([f, 0]);rr}r(hUh j~ubaubhW)r}r(hXMwould 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:rh hh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5K5h6hh]r(hSXJwould create a queue containing three commands, each calling the function rr}r(hXJwould create a queue containing three commands, each calling the function rh jubh)r}r(hX``f``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXfr}r(hUh jubah&jubhSX 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 rr}r(hX 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 rh jubh)r}r(hX``f``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXfr}r(hUh jubah&jubhSX[ is not a function that operates asynchronously, so it would have been easier to just call rr}r(hX[ is not a function that operates asynchronously, so it would have been easier to just call rh jubh)r}r(hX``f``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXfr}r(hUh jubah&jubhSXz four times directly. The power of the queue comes from calling commands that could operate asynchronously. For example:rr}r(hXz four times directly. The power of the queue comes from calling commands that could operate asynchronously. For example:rh jubeubj})r}r(hXfunction f(x) {alert(x)} MathJax.Callback.Queue( [f, 1], ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"], [f, 2] );rh hh!h$h&jh(}r(jjX javascriptrjjh*]rh,]rh.]rh0]rh2]ruh5KGh6hh]rhSXfunction f(x) {alert(x)} MathJax.Callback.Queue( [f, 1], ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"], [f, 2] );rr}r(hUh jubaubhW)r}r(hXGHere, the command ``MathJax.Ajax.require("extensions/AMSmath.js")`` is queued between two calls to ``f``. The first call to ``f(1)`` will be made immediately, then the :meth:`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 torh hh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5KHh6hh]r(hSXHere, the command rr}r(hXHere, the command rh jubh)r}r(hX1``MathJax.Ajax.require("extensions/AMSmath.js")``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSX-MathJax.Ajax.require("extensions/AMSmath.js")rr}r(hUh jubah&jubhSX is queued between two calls to rr}r(hX is queued between two calls to rh jubh)r}r(hX``f``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXfr}r(hUh jubah&jubhSX. The first call to rr }r (hX. The first call to r h jubh)r }r (hX``f(1)``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXf(1)rr}r(hUh j ubah&jubhSX$ will be made immediately, then the rr}r(hX$ will be made immediately, then the rh jubh)r}r(hX:meth:`MathJax.Ajax.Require`rh jh&hh(}r (Ureftyper!Xmethr"hXMathJax.Ajax.Requirer#U refdomainr$Xpyr%h*]r&h,]r'U refexplicitr(h.]r)h0]r*h2]r+hhhNhNuh5KHh]r,h)r-}r.(hjh(}r/(h.]r0h0]r1(hj%Xpy-methr2eh,]r3h*]r4h2]r5uh jh]r6hSXMathJax.Ajax.Require()r7r8}r9(hUh j-ubah&jubaubhSX) statement will be performed. Since the r:r;}r<(hX) statement will be performed. Since the r=h jubh)r>}r?(hX ``Require``r@h(}rA(h.]rBh0]rCh,]rDh*]rEh2]rFuh jh]rGhSXRequirerHrI}rJ(hUh j>ubah&jubhSXL method loads a file, it operates asynchronously, and its return value is a rKrL}rM(hXL method loads a file, it operates asynchronously, and its return value is a rNh jubhg)rO}rP(hX`MathJax.Callback`rQh(}rR(h.]rSh0]rTh,]rUh*]rVh2]rWuh jh]rXhSXMathJax.CallbackrYrZ}r[(hUh jOubah&huubhSXB object that will be called when the file is loaded. The call to r\r]}r^(hXB object that will be called when the file is loaded. The call to r_h jubh)r`}ra(hX``f(2)``rbh(}rc(h.]rdh0]reh,]rfh*]rgh2]rhuh jh]rihSXf(2)rjrk}rl(hUh j`ubah&jubhSXa will not be made until that callback is performed, effectively synchronizing the second call to rmrn}ro(hXa will not be made until that callback is performed, effectively synchronizing the second call to rph jubh)rq}rr(hX``f``rsh(}rt(h.]ruh0]rvh,]rwh*]rxh2]ryuh jh]rzhSXfr{}r|(hUh jqubah&jubhSX@ with the completion of the file loading. This is equivalent tor}r~}r(hX@ with the completion of the file loading. This is equivalent torh jubeubj})r}r(hXFf(1); MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js", [f, 2]);rh hh!h$h&jh(}r(jjX javascriptrjjh*]rh,]rh.]rh0]rh2]ruh5KVh6hh]rhSXFf(1); MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js", [f, 2]);rr}r(hUh jubaubhW)r}r(hXsince 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.rh hh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5KWh6hh]r(hSX since the rr}r(hX since the rh jubh)r}r(hX ``Require()``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSX Require()rr}r(hUh jubah&jubhSX 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.rr}r(hX 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.rh jubeubhW)r}r(hX For example,rh hh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5K\h6hh]rhSX For example,rr}r(hjh jubaubj})r}r(hXMathJax.Callback.Queue( ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"], [f, 1], ["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"], [f, 2] );rh hh!h$h&jh(}r(jjX javascriptrjjh*]rh,]rh.]rh0]rh2]ruh5Kfh6hh]rhSXMathJax.Callback.Queue( ["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"], [f, 1], ["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"], [f, 2] );rr}r(hUh jubaubhW)r}r(hXwould 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.rh hh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kgh6hh]r(hSX,would load the AMSmath extension, then call rr}r(hX,would load the AMSmath extension, then call rh jubh)r}r(hX``f(1)``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXf(1)rr}r(hUh jubah&jubhSX: then load the local AMSmath modifications, and then call rr}r(hX: then load the local AMSmath modifications, and then call rh jubh)r}r(hX``f(2)``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXf(2)rr}r(hUh jubah&jubhSXZ, with each action waiting for the previous one to complete before being performed itself.rr}r(hXZ, with each action waiting for the previous one to complete before being performed itself.rh jubeubeubh8)r}r(hUh h9h!h$h&h=h(}r(h.]rh0]rh,]rh*]rhah2]rh auh5Knh6hh]r(hG)r}r(hX(Callbacks versus Callback Specificationsrh jh!h$h&hKh(}r(h.]rh0]rh,]rh*]r h2]r uh5Knh6hh]r hSX(Callbacks versus Callback Specificationsr r }r(hjh jubaubhW)r}r(hXIf 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,rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kph6hh]rhSXIf 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,rr}r(hjh jubaubj})r}r(hXs MathJax.Callback.Queue( [f, 1], MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"), [f, 2], );rh jh!h$h&jh(}r(jjX javascriptr jjh*]r!h,]r"h.]r#h0]r$h2]r%uh5K{h6hh]r&hSXs MathJax.Callback.Queue( [f, 1], MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"), [f, 2], );r'r(}r)(hUh jubaubhW)r*}r+(hXfstarts 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.r,h jh!h$h&h[h(}r-(h.]r.h0]r/h,]r0h*]r1h2]r2uh5K|h6hh]r3(hSX{starts the loading of the AMSmath extension before the queue is created, and then creates the queue containing the call to r4r5}r6(hX{starts the loading of the AMSmath extension before the queue is created, and then creates the queue containing the call to r7h j*ubh)r8}r9(hX``f``r:h(}r;(h.]r<h0]r=h,]r>h*]r?h2]r@uh j*h]rAhSXfrB}rC(hUh j8ubah&jubhSX9, the callback for the file load, and the second call to rDrE}rF(hX9, the callback for the file load, and the second call to rGh j*ubh)rH}rI(hX``f``rJh(}rK(h.]rLh0]rMh,]rNh*]rOh2]rPuh j*h]rQhSXfrR}rS(hUh jHubah&jubhSX. The queue performs rTrU}rV(hX. The queue performs rWh j*ubh)rX}rY(hX``f(1)``rZh(}r[(h.]r\h0]r]h,]r^h*]r_h2]r`uh j*h]rahSXf(1)rbrc}rd(hUh jXubah&jubhSX@, waits for the file load callback to be called, and then calls rerf}rg(hX@, waits for the file load callback to be called, and then calls rhh j*ubh)ri}rj(hX``f(2)``rkh(}rl(h.]rmh0]rnh,]roh*]rph2]rquh j*h]rrhSXf(2)rsrt}ru(hUh jiubah&jubhSX. 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 rvrw}rx(hX. 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 ryh j*ubh)rz}r{(hX``f(1)``r|h(}r}(h.]r~h0]rh,]rh*]rh2]ruh j*h]rhSXf(1)rr}r(hUh jzubah&jubhSXS, while in the example above, the file load is guaranteed not to begin until after rr}r(hXS, while in the example above, the file load is guaranteed not to begin until after rh j*ubh)r}r(hX``f(1)``rh(}r(h.]rh0]rh,]rh*]rh2]ruh j*h]rhSXf(1)rr}r(hUh jubah&jubhSX is executed.rr}r(hX is executed.rh j*ubeubhW)r}r(hXAs a further example, considerrh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]rhSXAs a further example, considerrr}r(hjh jubaubj})r}r(hXMathJax.Callback.Queue( MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"), [f, 1], MathJax.Ajax.Require("[MathJax]/config/local/AMSmathAdditions.js"), [f, 2] );rh jh!h$h&jh(}r(jjX javascriptrjjh*]rh,]rh.]rh0]rh2]ruh5Kh6hh]rhSXMathJax.Callback.Queue( MathJax.Ajax.Require("[MathJax]/extensions/AMSmath.js"), [f, 1], MathJax.Ajax.Require("[MathJax]/config/local/AMSmathAdditions.js"), [f, 2] );rr}r(hUh jubaubhW)r}r(hXIin 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.rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]r(hSX-in comparison to the example above that uses rr}r(hX-in comparison to the example above that uses rh jubh)r}r(hX@``["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"]``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSX<["Require", MathJax.Ajax, "[MathJax]/extensions/AMSmath.js"]rr}r(hUh jubah&jubhSX and rr}r(hX and rh jubh)r}r(hXK``["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"]``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXG["Require", MathJax.Ajax, "[MathJax]/config/local/AMSmathAdditions.js"]rr}r(hUh jubah&jubhSX instead. In that example, rr}r(hX instead. In that example, rh jubh)r}r(hX``AMSmath.js``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSX AMSmath.jsrr}r(hUh jubah&jubhSX is loaded, then rr}r(hX is loaded, then rh jubh)r}r(hX``f(1)``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXf(1)rr}r(hUh jubah&jubhSX6 is called, then the local additions are loaded, then rr}r(hX6 is called, then the local additions are loaded, then rh jubh)r }r (hX``f(2)``r h(}r (h.]r h0]rh,]rh*]rh2]ruh jh]rhSXf(2)rr}r(hUh j ubah&jubhSX is called.rr}r(hX is called.rh jubeubhW)r}r(hXHere, 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.rh jh!h$h&h[h(}r(h.]rh0]rh,]r h*]r!h2]r"uh5Kh6hh]r#(hSX)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 r$r%}r&(hX)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 r'h jubcdocutils.nodes strong r()r)}r*(hX**not**r+h(}r,(h.]r-h0]r.h,]r/h*]r0h2]r1uh jh]r2hSXnotr3r4}r5(hUh j)ubah&Ustrongr6ubhSX5 to happen in the other example. Note, however, that r7r8}r9(hX5 to happen in the other example. Note, however, that r:h jubh)r;}r<(hX``f(1)``r=h(}r>(h.]r?h0]r@h,]rAh*]rBh2]rCuh jh]rDhSXf(1)rErF}rG(hUh j;ubah&jubhSXP is guaranteed not to be performed until after the AMSmath extensions load, and rHrI}rJ(hXP is guaranteed not to be performed until after the AMSmath extensions load, and rKh jubh)rL}rM(hX``f(2)``rNh(}rO(h.]rPh0]rQh,]rRh*]rSh2]rTuh jh]rUhSXf(2)rVrW}rX(hUh jLubah&jubhSX2 will not occur until after both files are loaded.rYrZ}r[(hX2 will not occur until after both files are loaded.r\h jubeubhW)r]}r^(hXIn 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,r_h jh!h$h&h[h(}r`(h.]rah0]rbh,]rch*]rdh2]reuh5Kh6hh]rfhSXIn 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,rgrh}ri(hj_h j]ubaubj})rj}rk(hXMathJax.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"] );rlh jh!h$h&jh(}rm(jjX javascriptrnjjh*]roh,]rph.]rqh0]rrh2]rsuh5Kh6hh]rthSXMathJax.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"] );rurv}rw(hUh jjubaubhW)rx}ry(hXstarts 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.rzh jh!h$h&h[h(}r{(h.]r|h0]r}h,]r~h*]rh2]ruh5Kh6hh]r(hSXYstarts four files loading all at once, and waits for all four to complete before calling rr}r(hXYstarts four files loading all at once, and waits for all four to complete before calling rh jxubh)r}r(hX``f("all done")``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jxh]rhSX f("all done")rr}r(hUh jubah&jubhSXb. The order in which they complete is immaterial, and they all are being requested simultaneously.rr}r(hXb. The order in which they complete is immaterial, and they all are being requested simultaneously.rh jxubeubeubh8)r}r(hUh h9h!h$h&h=h(}r(h.]rh0]rh,]rh*]rhah2]rh auh5Kh6hh]r(hG)r}r(hXThe MathJax Processing Queuerh jh!h$h&hKh(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]rhSXThe MathJax Processing Queuerr}r(hjh jubaubhW)r}r(hXMathJax 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.rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]r(hSXMathJax uses a queue stored as rr}r(hXMathJax uses a queue stored as rh jubh)r}r(hX``MathJax.Hub.queue``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXMathJax.Hub.queuerr}r(hUh jubah&jubhSX_ 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.rr}r(hX_ 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.rh jubeubhW)r}r(hXThe 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.rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]rhSXThe 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.rr}r(hjh jubaubhW)r}r(hXAs a result, any call to :meth:`MathJax.Hub.Typeset()` (or :meth:`MathJax.Hub.Process()`, or :meth:`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 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.rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]r(hSXAs a result, any call to rr}r(hXAs a result, any call to rh jubh)r}r(hX:meth:`MathJax.Hub.Typeset()`rh jh&hh(}r(UreftyperXmethrhXMathJax.Hub.TypesetrU refdomainrXpyrh*]rh,]rU refexplicitrh.]rh0]rh2]rhhhNhNuh5Kh]rh)r}r(hjh(}r(h.]rh0]r(hjXpy-methreh,]rh*]rh2]ruh jh]rhSXMathJax.Hub.Typeset()rr}r(hUh jubah&jubaubhSX (or rr}r(hX (or rh jubh)r}r (hX:meth:`MathJax.Hub.Process()`r h jh&hh(}r (Ureftyper Xmethr hXMathJax.Hub.ProcessrU refdomainrXpyrh*]rh,]rU refexplicitrh.]rh0]rh2]rhhhNhNuh5Kh]rh)r}r(hj h(}r(h.]rh0]r(hjXpy-methreh,]rh*]rh2]r uh jh]r!hSXMathJax.Hub.Process()r"r#}r$(hUh jubah&jubaubhSX, or r%r&}r'(hX, or r(h jubh)r)}r*(hX:meth:`MathJax.Hub.Update()`r+h jh&hh(}r,(Ureftyper-Xmethr.hXMathJax.Hub.Updater/U refdomainr0Xpyr1h*]r2h,]r3U refexplicitr4h.]r5h0]r6h2]r7hhhNhNuh5Kh]r8h)r9}r:(hj+h(}r;(h.]r<h0]r=(hj1Xpy-methr>eh,]r?h*]r@h2]rAuh j)h]rBhSXMathJax.Hub.Update()rCrD}rE(hUh j9ubah&jubaubhSXP, 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.rFrG}rH(hXP, 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.rIh jubeubhW)rJ}rK(hXFurthermore, 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.rLh jh!h$h&h[h(}rM(h.]rNh0]rOh,]rPh*]rQh2]rRuh5Kh6hh]rS(hSXFurthermore, 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 rTrU}rV(hXFurthermore, 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 rWh jJubj+)rX}rY(hX *previous*rZh(}r[(h.]r\h0]r]h,]r^h*]r_h2]r`uh jJh]rahSXpreviousrbrc}rd(hUh jXubah&j9ubhSX 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.rerf}rg(hX 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.rhh jJubeubhW)ri}rj(hX~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.rkh jh!h$h&h[h(}rl(h.]rmh0]rnh,]roh*]rph2]rquh5Kh6hh]rrhSX~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.rsrt}ru(hjkh jiubaubhW)rv}rw(hXbTo place an action in the MathJax queue, use the :meth:`MathJax.Hub.Queue()` command. For examplerxh jh!h$h&h[h(}ry(h.]rzh0]r{h,]r|h*]r}h2]r~uh5Kh6hh]r(hSX1To place an action in the MathJax queue, use the rr}r(hX1To place an action in the MathJax queue, use the rh jvubh)r}r(hX:meth:`MathJax.Hub.Queue()`rh jvh&hh(}r(UreftyperXmethrhXMathJax.Hub.QueuerU refdomainrXpyrh*]rh,]rU refexplicitrh.]rh0]rh2]rhhhNhNuh5Kh]rh)r}r(hjh(}r(h.]rh0]r(hjXpy-methreh,]rh*]rh2]ruh jh]rhSXMathJax.Hub.Queue()rr}r(hUh jubah&jubaubhSX command. For examplerr}r(hX command. For examplerh jvubeubj})r}r(hX5MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);rh jh!h$h&jh(}r(jjX javascriptrjjh*]rh,]rh.]rh0]rh2]ruh5Kh6hh]rhSX5MathJax.Hub.Queue(["Typeset",MathJax.Hub,"MathDiv"]);rr}r(hUh jubaubhW)r}r(hXwould queue the command ``MathJax.Hub.Typeset("MathDiv")``, causing the contents of the DOM element with `id` equal to ``MathDiv`` to be typeset.rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]r(hSXwould queue the command rr}r(hXwould queue the command rh jubh)r}r(hX"``MathJax.Hub.Typeset("MathDiv")``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXMathJax.Hub.Typeset("MathDiv")rr}r(hUh jubah&jubhSX/, causing the contents of the DOM element with rr}r(hX/, causing the contents of the DOM element with rh jubhg)r}r(hX`id`rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXidrr}r(hUh jubah&huubhSX equal to rr}r(hX equal to rh jubh)r}r(hX ``MathDiv``rh(}r(h.]rh0]rh,]rh*]rh2]ruh jh]rhSXMathDivrr}r(hUh jubah&jubhSX to be typeset.rr}r(hX to be typeset.rh jubeubhW)r}r(hXOne 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,rh jh!h$h&h[h(}r(h.]rh0]rh,]rh*]rh2]ruh5Kh6hh]r(hSXOne 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 rr}r(hXOne 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 rh jubh)r}r(hX``MathJax.Hub.queue``rh(}r(h.]rh0]rh,]rh*]r h2]r uh jh]r hSXMathJax.Hub.queuer r }r(hUh jubah&jubhSXp so that it won't be performed until MathJax finishes everything it has queued when it was loaded. For example,rr}r(hXp so that it won't be performed until MathJax finishes everything it has queued when it was loaded. For example,rh jubeubj})r}r(hX rh jh!h$h&jh(}r(jjXhtmlrjjh*]rh,]rh.]rh0]rh2]ruh5Kh6hh]rhSX rr}r (hUh jubaubeubeubehUU transformerr!NU footnote_refsr"}r#Urefnamesr$}r%Usymbol_footnotesr&]r'Uautofootnote_refsr(]r)Usymbol_footnote_refsr*]r+U citationsr,]r-h6hU current_liner.NUtransform_messagesr/]r0cdocutils.nodes system_message r1)r2}r3(hUh(}r4(h.]r5Ulevelr6Kh*]r7h,]r8Usourcer9h$h0]r:h2]r;Uliner<KUtyper=UINFOr>uh]r?hW)r@}rA(hUh(}rB(h.]rCh0]rDh,]rEh*]rFh2]rGuh j2h]rHhSX2Hyperlink target "using-queues" is not referenced.rIrJ}rK(hUh j@ubah&h[ubah&Usystem_messagerLubaUreporterrMNUid_startrNKU autofootnotesrO]rPU citation_refsrQ}rRUindirect_targetsrS]rTUsettingsrU(cdocutils.frontend Values rVorW}rX(Ufootnote_backlinksrYKUrecord_dependenciesrZNU rfc_base_urlr[Uhttp://tools.ietf.org/html/r\U tracebackr]KUpep_referencesr^NUstrip_commentsr_NU toc_backlinksr`UentryraU language_coderbUenrcU datestamprdNU report_levelreKU _destinationrfNU halt_levelrgKU strip_classesrhNhKNUerror_encoding_error_handlerriUbackslashreplacerjUdebugrkNUembed_stylesheetrlUoutput_encoding_error_handlerrmUstrictrnU sectnum_xformroKUdump_transformsrpNU docinfo_xformrqKUwarning_streamrrNUpep_file_url_templatersUpep-%04drtUexit_status_levelruKUconfigrvNUstrict_visitorrwNUcloak_email_addressesrxUtrim_footnote_reference_spaceryUenvrzNUdump_pseudo_xmlr{NUexpose_internalsr|NUsectsubtitle_xformr}U source_linkr~NUrfc_referencesrNUoutput_encodingrUutf-8rU source_urlrNUinput_encodingrU utf-8-sigrU_disable_configrNU id_prefixrUU tab_widthrKUerror_encodingrUUTF-8rU_sourcerUP/Data/Code/JavaScript/MathJax/Code/SourceForge/trunk/mathjax/docs/rst/queues.rstrU generatorrNUdump_internalsrNU pep_base_urlrUhttp://www.python.org/dev/peps/rUinput_encoding_error_handlerrjnUauto_id_prefixrUidrUdoctitle_xformrUstrip_elements_with_classesrNU _config_filesr]rUfile_insertion_enabledrKU raw_enabledrKU dump_settingsrNubUsymbol_footnote_startrKUidsr}r(hjhhhjhh9hh9uUsubstitution_namesr}rh&h6h(}r(h.]rh*]rh,]rUsourcerh$h0]rh2]ruU footnotesr]rUrefidsr}rh]rhasub.