155 lines
6.1 KiB
ReStructuredText
155 lines
6.1 KiB
ReStructuredText
.. _api-signal:
|
|
|
|
*********************************
|
|
The MathJax.Callback.Signal Class
|
|
*********************************
|
|
|
|
The ``MathJax.Callback.Signal`` object is one of the key mechanisms
|
|
used by MathJax to synchronize its actions with those that occur
|
|
asynchronously, like loading files and stylesheets. A `Signal` object
|
|
is used to publicize the fact that MathJax has performed certain
|
|
actions, giving other code running the web page the chance to react to
|
|
those actions. See :ref:`Synchronizing with MathJax
|
|
<synchronization>` for more details, and :ref:`Using Signals
|
|
<using-signals>` in particular for examples of how to specify and use
|
|
MathJax `Signal` objects.
|
|
|
|
The `Callback Signal` object is a subclass of the :ref:`Callback Queue
|
|
<api-queue>` object.
|
|
|
|
|
|
Properties
|
|
----------
|
|
|
|
.. describe:: name
|
|
|
|
The name of the signal. Each signal is named so that
|
|
various components can access it. The first one to request a
|
|
particular signal causes it to be created, and other requests for
|
|
the signal return references to the same object.
|
|
|
|
.. describe:: posted
|
|
|
|
Array used internally to store the post history so that when new
|
|
listeners express interests in this signal, they can be informed
|
|
of the signals that have been posted so far. This can be cleared
|
|
using the signal's :meth:`Clear()` method.
|
|
|
|
.. describe:: listeners
|
|
|
|
Array of callbacks to the listeners who have expressed interest in
|
|
hearing about posts to this signal. When a post occurs, the
|
|
listeners are called, each in turn, passing them the message that
|
|
was posted.
|
|
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. method:: Post(message[,callback])
|
|
|
|
Posts a message to all the listeners for the signal. The listener
|
|
callbacks are called in turn (with the message as an argument),
|
|
and if any return a `Callback` object, the posting will be
|
|
suspended until the callback is executed. In this way, the
|
|
:meth:`Post()` call can operate asynchronously, and so the
|
|
`callback` parameter is used to synchronize with its operation;
|
|
the `callback` will be called when all the listeners have responded
|
|
to the post.
|
|
|
|
If a :meth:`Post()` to this signal occurs while waiting for the
|
|
response from a listener (either because a listener returned a
|
|
`Callback` object and we are waiting for it to complete when the
|
|
:meth:`Post()` occurred, or because the listener itself called the
|
|
``Post()`` method), the new message will be queued and will be
|
|
posted after the current message has been sent to all the
|
|
listeners, and they have all responded. This is another way in
|
|
which posting can be asynchronous; the only sure way to know that
|
|
a posting has occurred is through its `callback`. When the posting
|
|
is complete, the callback is called, passing it the signal object
|
|
that has just completed.
|
|
|
|
Returns the callback object (or a blank callback object if none
|
|
was provided).
|
|
|
|
:Parameters:
|
|
- **message** --- the message to send through the signal
|
|
- **callback** --- called after the message is posted
|
|
:Returns: the callback or a blank callback
|
|
|
|
.. method:: Clear([callback])
|
|
:noindex:
|
|
|
|
This causes the history of past messages to be cleared so new
|
|
listeners will not receive them. Note that since the signal may
|
|
be operating asynchronously, the :meth:`Clear()` may be queued for
|
|
later. In this way, the :meth:`Post()` and :meth:`Clear()`
|
|
operations will be performed in the proper order even when they
|
|
are delayed. The `callback` is called when the :meth:`Clear()`
|
|
operation is completed.
|
|
|
|
Returns the callback (or a blank callback if none is provided).
|
|
|
|
:Parameters:
|
|
- **callback** --- called after the signal history is cleared
|
|
:Returns: the callback or a blank callback
|
|
|
|
.. method:: Interest(callback[,ignorePast])
|
|
|
|
This method registers a new listener on the signal. It creates a
|
|
`Callback` object from the callback specification, attaches it to
|
|
the signal, and returns that `Callback` object. When new messages
|
|
are posted to the signal, it runs the callback, passing it the
|
|
message that was posted. If the callback itself returns a
|
|
`Callback` object, that indicates that the listener has started an
|
|
asynchronous operation and the poster should wait for that
|
|
callback to complete before allowing new posts on the signal.
|
|
|
|
If `ignorePast` is ``false`` or not present, then before
|
|
:meth:`Interest()` returns, the callback will be called with all
|
|
the past messages that have been sent to the signal.
|
|
|
|
:Parameters:
|
|
- **callback** --- called whenever a message is posted (past or present)
|
|
- **ignorePast** --- ``true`` means ignore previous messages
|
|
:Returns: the callback object
|
|
|
|
.. method:: NoInterest(callback)
|
|
|
|
This removes a listener from the signal so that no new messages
|
|
will be sent to it. The callback should be the one returned by
|
|
the original :meth:`Interest()` call that attached the listener to
|
|
the signal in the first place. Once removed, the listener will no
|
|
longer receive messages from the signal.
|
|
|
|
:Parameters:
|
|
- **callback** --- the listener to be removed from signal
|
|
:Returns: ``null``
|
|
|
|
.. method:: MessageHook(message, callback)
|
|
|
|
This creates a callback that is called whenever the signal posts
|
|
the given message. This is a little easier than having to write a
|
|
function that must check the message each time it is called.
|
|
Although the `message` here is a string, if a message posted to the
|
|
signal is an array, then only the first element of that array is
|
|
used to match against the message. That way, if a message contains an
|
|
identifier plus arguments, the hook will match the identifier and
|
|
still get called with the complete set of arguments.
|
|
|
|
Returns the `Callback` object that was produced.
|
|
|
|
:Parameters:
|
|
- **message** --- the message to look for from the signal
|
|
- **callback** --- called when the message is posted
|
|
:Returns: the callback object
|
|
|
|
.. method:: ExecuteHook(message)
|
|
|
|
Used internally to call the listeners when a particular
|
|
message is posted to the signal.
|
|
|
|
:Parameters:
|
|
- **message** --- the posted message
|
|
:Returns: ``null``
|