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.

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.

The 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

Trigger the run engine to start bundling future obj.read() calls for

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.complete

Tell a flyer, ‘stop collecting, whenever you are ready’.

RunBundler.collect

Collect data cached by a flyer and emit documents.

RunBundler.backstop_collect

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.