.. currentmodule:: bluesky.run_engine

RunEngine API Documentation
===========================

The ``RunEngine``
-----------------

.. autosummary::
   :nosignatures:
   :toctree: generated

    RunEngine

The main user entry point tho the RunEngine is ``RE(my_plan(...))``

.. autosummary::
   :nosignatures:
   :toctree: generated

    RunEngine.__call__

The RunEngine maintains a callback registry of functions that receive any
:doc:`documents` generated by plan execution. These methods add and remove
functions from that registry.


.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.subscribe
   RunEngine.unsubscribe

When the RunEngine is in a paused state, it can be resumed or stopped in
:ref:`various ways <interactive_pause_summary>` using these methods:


.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.resume
   RunEngine.abort
   RunEngine.stop
   RunEngine.halt

The RunEngine can suspend and resume plan execution in response to external
changes. See :ref:`suspenders`.


.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.install_suspender
   RunEngine.remove_suspender
   RunEngine.clear_suspenders

These methods are used internally to pause or suspend the RunEngine.
Typically the user accomplishes this with Ctrl+C or by installing
suspenders, respectively. For special applicaitons, they can be called
directly.


.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.request_pause
   RunEngine.request_suspend

These methods may be used to register custom commands to supplement or
replace the built-in commands recognized by the RunEngine.


.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.register_command
   RunEngine.unregister_command

These methods may be used to list the commands available, or print
a summary as to what they do.

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunEngine.print_command_registry
   RunEngine.commands

A RunEngine encapsulates a :class:`Dispatcher` for emitting any
:doc:`documents` generated by plan execution. The methods
:meth:`RunEngine.subscribe` and :meth:`RunEngine.unsubscribe`, documented
above, are aliases to the corresponding methods on the RunEngine's Dispatcher.


The ``Dispatcher``
------------------


.. autosummary::
   :nosignatures:
   :toctree: generated

   Dispatcher
   Dispatcher.subscribe
   Dispatcher.unsubscribe
   Dispatcher.unsubscribe_all
   Dispatcher.process


The ``RunBundler``
------------------


The RunEngine also creates `RunBundler`\s instances to encapsulate the
logic and book keeping for generating events (and allow multiple runs
to be open at once).  In general you should not be directly working with
a `RunBundler`.

.. currentmodule:: bluesky.bundlers

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler

The co-routines for opening and closing a run.

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.open_run
   RunBundler.close_run

The co-routines for opening / filling / closing / dropping an Event

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.create
   RunBundler.read
   RunBundler.drop
   RunBundler.save

The co-routines for managing flyers

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.kickoff
   RunBundler.complete
   RunBundler.collect
   RunBundler.backstop_collect

The co-routines for changing a device configuration

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.configure

The co-routines for managing monitors

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.monitor
   RunBundler.suspend_monitors
   RunBundler.restore_monitors
   RunBundler.clear_monitors
   RunBundler.unmonitor

The co-routines for checkpoint management

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.clear_checkpoint
   RunBundler.reset_checkpoint_state
   RunBundler.reset_checkpoint_state_coro
   RunBundler.rewind

The co-routines to record interruptions

.. autosummary::
   :nosignatures:
   :toctree: generated

   RunBundler.record_interruption