bluesky.run_engine.RunEngine

class bluesky.run_engine.RunEngine(md=None, *, loop=None, preprocessors=None, context_managers=None, md_validator=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.

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.

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, 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

commands

The list of commands available to Msg.

ignore_callback_exceptions

loop

resumable

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

rewindable

state

suspenders

verbose