bluesky.run_engine.RunEngine#

class bluesky.run_engine.RunEngine(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, md_normalizer=None, scan_id_source=<function default_scan_id_source>, during_task=None, call_returns_result=False)[source]#

The Run Engine execute messages and emits Documents.

Parameters:
mddict-like, optional

The default is a standard Python dictionary, but fancier objects can be used to store long-term history and persist it between sessions. The standard configuration instantiates a Run Engine with historydict.HistoryDict, a simple interface to a sqlite file. Any object supporting __getitem__, __setitem__, and clear will work.

loopasyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

preprocessorslist, optional

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

context_managerslist, optional

Context managers that will be entered when we run a plan. The context managers will be composed in order, much like the preprocessors. If this argument is omitted, we will use a user-oriented handler for SIGINT. The elements of this list will be passed this RunEngine instance as their only argument. You may pass an empty list if you would like a RunEngine with no signal handling and no context managers.

md_validatorcallable, optional

a function that raises and prevents starting a run if it deems the metadata to be invalid or incomplete Expected signature: f(md) Function should raise if md is invalid. What that means is completely up to the user. The function’s return value is ignored.

md_normalizercallable, optional

a function that, similar to md_validator, raises and prevents starting a run if it deems the metadata to be invalid or incomplete. If it succeeds, it returns the normalized/transformed version of the original metadata. Expected signature: f(md) Function should raise if md is invalid. What that means is completely up to the user. Expected return: normalized metadata

scan_id_sourcecallable, optional

a function that will be used to calculate scan_id. Default is to increment scan_id by 1 each time. However you could pass in a customized function to get a scan_id from any source. Expected signature: f(md) Expected return: updated scan_id value

during_taskreference to an object of class DuringTask, optional

Class methods: block() to be run to block the main thread during RE.__call__

The required signatures for the class methods

def block(ev: Threading.Event) -> None:
    "Returns when ev is set"
The default value handles the cases of:
  • Matplotlib is not imported (just wait on the event)

  • Matplotlib is imported, but not using a Qt, notebook or ipympl backend (just wait on the event)

  • Matplotlib is imported and using a Qt backend (run the Qt app on the main thread until the run finishes)

  • Matplotlib is imported and using a nbagg or ipympl backend ( wait on the event and poll to push updates to the browser)

call_returns_resultbool, default False

A flag that controls the return value of __call__ If True, the RunEngine will return a :class:RunEngineResult object that contains information about the plan that was run. If False, the RunEngine will return a tuple of uids. Defaults to False to preserve the old RunEngine behavior, but the default is expected to change to True in the future.

Attributes:
md

Direct access to the dict-like persistent storage described above

record_interruptions

False by default. Set to True to generate an extra event stream that records any interruptions (pauses, suspensions).

state

{‘idle’, ‘running’, ‘paused’}

suspenders

Read-only collection of bluesky.suspenders.SuspenderBase objects which can suspend and resume execution; see related methods.

preprocessorslist

Generator functions that take in a plan (generator instance) and modify its messages on the way out. Suitable examples include the functions in the module bluesky.plans with names ending in ‘wrapper’. Functions are composed in order: the preprocessors [f, g] are applied like f(g(plan)).

msg_hook

Callable that receives all messages before they are processed (useful for logging or other development purposes); expected signature is f(msg) where msg is a bluesky.Msg, a kind of namedtuple; default is None.

state_hook

Callable with signature f(new_state, old_state) that will be called whenever the RunEngine’s state attribute is updated; default is None

waiting_hook

Callable with signature f(status_object) that will be called whenever the RunEngine is waiting for long-running commands (trigger, set, kickoff, complete) to complete. This hook is useful to incorporate a progress bar.

ignore_callback_exceptions

Boolean, False by default.

call_returns_result

Boolean, False by default. If False, RunEngine will return uuid list after running a plan. If True, RunEngine will return a RunEngineResult object that contains the plan result, error status, and uuid list.

loopasyncio event loop

e.g., asyncio.get_event_loop() or asyncio.new_event_loop()

max_depth

Maximum stack depth; set this to prevent users from calling the RunEngine inside a function (which can result in unexpected behavior and breaks introspection tools). Default is None. For built-in Python interpreter, set to 2. For IPython, set to 11 (tested on IPython 5.1.0; other versions may vary).

pause_msgstr

The message printed when a run is interrupted. This message includes instructions of changing the state of the RunEngine. It is set to bluesky.run_engine.PAUSE_MSG by default and can be modified based on needs.

commands:

The list of commands available to Msg.

__init__(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=None, md_normalizer=None, scan_id_source=<function default_scan_id_source>, during_task=None, call_returns_result=False)[source]#

Methods

__init__([md, loop, preprocessors, ...])

abort([reason])

Stop a running or paused plan and mark it as aborted.

clear_suspenders()

Uninstall all suspenders.

emit(name, doc)

emit_sync(name, doc)

Process blocking callbacks and schedule non-blocking callbacks.

halt()

Stop the running plan and do not allow the plan a chance to clean up.

install_suspender(suspender)

Install a 'suspender', which can suspend and resume execution.

print_command_registry([verbose])

This conveniently prints the command registry of available commands.

register_command(name, func)

Register a new Message command.

remove_suspender(suspender)

Uninstall a suspender.

request_pause([defer])

Command the Run Engine to pause.

request_suspend(fut, *[, pre_plan, ...])

Request that the run suspend itself until the future is finished.

reset()

Clean up caches and unsubscribe subscriptions.

resume()

Resume a paused plan from the last checkpoint.

stop()

Stop a running or paused plan, but mark it as successful (not aborted).

subscribe(func[, name])

Register a callback function to consume documents.

unregister_command(name)

Unregister a Message command.

unsubscribe(token)

Unregister a callback function its integer ID.

Attributes

call_returns_result

commands

The list of commands available to Msg.

deferred_pause_requested

The property returns True if deferred pause was requested, but not processed.

ignore_callback_exceptions

loop

resumable

i.e., can the plan in progress by rewound

rewindable

state

suspenders

verbose