.. role:: ts-api-decorator

#############
CurrentAction
#############

.. js:module:: Util
   :noindex:

.. container:: ts-api-section

   .. js:class:: CurrentAction

      This class encapsulates execution of a single action at a time.
      You set the action to execute, which waits on the currently executing
      action and kills any pending ones.

      This class can be thought of as an ``Action`` queue  that limits to 1 action
      running at a time, and if any new actions are pushed into it, the queue's
      pending actions are cleared. (The actively running action will not get
      cancelled.)



.. container:: api-index-section

   .. rubric:: Constructors

   .. rst-class:: api-index-list-item api-kind-constructor api-parent-kind-class

   * :js:meth:`~Util.CurrentAction.constructor`



.. container:: api-index-section

   .. rubric:: Methods

   .. rst-class:: api-index-list-item api-kind-method api-parent-kind-class

   * :js:meth:`~Util.CurrentAction.clear`
   * :js:meth:`~Util.CurrentAction.isIdle`
   * :js:meth:`~Util.CurrentAction.set`
   * :js:meth:`~Util.CurrentAction.waitForIdle`





------------

Constructors
============

.. container:: ts-api-section

   .. js:function:: CurrentAction.constructor( suppressFailures)

      :param suppressFailures: Controls whether or not thrown action errors cause ``waitForIdle`` to throw.
      :type suppressFailures: boolean


      Creates a new ``CurrentAction``.


      :rtype: CurrentAction



Methods
=======

.. rst-class:: ts-api-section

clear
-----

.. js:method:: CurrentAction.clear()



   Clears and discards any pending actions. If an action is
   currently being executed, it remains unaffected by this.


   :rtype: void

.. rst-class:: ts-api-section

isIdle
------

.. js:method:: CurrentAction.isIdle()



   Queries the idle state of this object.

   :returns: ``true`` if there are no executing actions and ``false`` otherwise.


   :rtype: boolean

.. rst-class:: ts-api-section

set
---

.. js:method:: CurrentAction.set( action)

   :param action: None
   :type action: ActionLike


   Sets the action to execute to the one supplied.

   If this object is idle, then the action is immediately executed,
   and this object is no longer as long as the action is running.

   Otherwise if the object is not idle, then action becomes pended
   and will execute after the current one finishes. If an action is
   already pended, then the prior pending action is replaced by the
   newly supplied action and is discarded.


   :rtype: void

.. rst-class:: ts-api-section

waitForIdle
-----------

.. js:method:: CurrentAction.waitForIdle()



   Creates ``Promise`` that can be used to wait for this object to become idle.

   If this object was created with ``suppressFailures``, then the returned ``Promise``
   never throws. Otherwise action failures (from ``this.set``) propagate to the returned ``Promise``.

   :returns: The idle ``Promise``.


   :rtype: Promise <void>

