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.

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

The co-routines to record interruptions

RunBundler.record_interruption

Emit an event in the 'interruptions' event stream.