RunEngine API Documentation

The RunEngine

RunEngine

The Run Engine execute messages and emits Documents.

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

RunEngine.__call__

Execute a plan.

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

RunEngine.subscribe	Register a callback function to consume documents.
RunEngine.unsubscribe	Unregister a callback function its integer ID.

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

RunEngine.resume	Resume a paused plan from the last checkpoint.
RunEngine.abort	Stop a running or paused plan and mark it as aborted.
RunEngine.stop	Stop a running or paused plan, but mark it as successful (not aborted).
RunEngine.halt	Stop the running plan and do not allow the plan a chance to clean up.

The RunEngine can suspend and resume plan execution in response to external changes. See Automated Suspension.

RunEngine.install_suspender	Install a 'suspender', which can suspend and resume execution.
RunEngine.remove_suspender	Uninstall a suspender.
RunEngine.clear_suspenders	Uninstall all 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.

RunEngine.request_pause	Command the Run Engine to pause.
RunEngine.request_suspend	Request that the run suspend itself until the future is finished.

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

RunEngine.register_command	Register a new Message command.
RunEngine.unregister_command	Unregister a Message command.

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

RunEngine.print_command_registry	This conveniently prints the command registry of available commands.
RunEngine.commands	The list of commands available to Msg.

The RunEngineResult

A RunEngineResult will be returned if the RunEngine was created with call_returns_result=True. The default is currently False, so this behavior is opt-in for now, but will change to opt-out in the future.

The RunEngineResult class encapsulates useful information about the plan that was run, including the ultimate plan return value, run uids, exit status, and exceptions.

RunEngineResult

Information about the plan that was run

The Dispatcher

A RunEngine encapsulates a Dispatcher for emitting any Documents generated by plan execution. The methods RunEngine.subscribe() and RunEngine.unsubscribe(), documented above, are aliases to the corresponding methods on the RunEngine’s Dispatcher.

Dispatcher	Dispatch documents to user-defined consumers on the main thread.
Dispatcher.subscribe	Register a callback function to consume documents.
Dispatcher.unsubscribe	Unregister a callback function using its integer ID.
Dispatcher.unsubscribe_all	Unregister all callbacks from the dispatcher.
Dispatcher.process	Dispatch document doc of type name to the callback registry.

The RunBundler

The RunEngine also creates RunBundlers 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.

RunBundler

The co-routines for opening and closing a run.

RunBundler.open_run
RunBundler.close_run	Instruct the RunEngine to write the RunStop document

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

RunBundler.create	Start bundling future obj.read() calls for an Event document.
RunBundler.read	Add a reading to the open event bundle.
RunBundler.drop	Drop the event that is currently being bundled
RunBundler.save	Save the event that is currently being bundled

The co-routines for managing flyers

RunBundler.kickoff	Start a flyscan object.
RunBundler.collect	Collect data cached by a flyer and emit documents.
RunBundler.backstop_collect

Note: There is a complete plan stub and run engine call, which should be used after kickoff whose logic does not reside in the RunBundler.

The co-routines for changing a device configuration

RunBundler.configure

Configure an object

The co-routines for managing monitors

RunBundler.monitor	Monitor a signal.
RunBundler.suspend_monitors
RunBundler.restore_monitors
RunBundler.clear_monitors
RunBundler.unmonitor	Stop monitoring; i.e., remove the callback emitting event documents.

The co-routines for checkpoint management

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

The co-routines to record interruptions

RunBundler.record_interruption

Emit an event in the 'interruptions' event stream.