ophyd.status.StatusBase

class ophyd.status.StatusBase(*, timeout=None, settle_time=0, done=None, success=None)

Track the status of a potentially-lengthy action like moving or triggering.

Parameters

timeout: float, optional

The amount of time to wait before marking the Status as failed. If None (default) wait forever. It is strongly encouraged to set a finite timeout. If settle_time below is set, that time is added to the effective timeout.

settle_time: float, optional

The amount of time to wait between the caller specifying that the status has completed to running callbacks. Default is 0.

Notes

Theory of operation:

This employs two threading.Event objects, one thread the runs for (timeout + settle_time) seconds, and one thread that runs for settle_time seconds (if settle_time is nonzero).

At __init__ time, a timeout and settle_time are specified. A thread is started, on which user callbacks, registered after __init__ time via add_callback(), will eventually be run. The thread waits on an Event be set or (timeout + settle_time) seconds to pass, whichever happens first.

If (timeout + settle_time) expires and the Event has not been set, an internal Exception is set to StatusTimeoutError, and a second Event is set, marking the Status as done and failed. The callbacks are run.

If a callback is registered after the Status is done, it will be run immediately.

If the first Event is set before (timeout + settle_time) expires, then the second Event is set and no internal Exception is set, marking the Status as done and successful. The callbacks are run.

There are two methods that directly set the first Event. One, :meth:set_exception, sets it directly after setting the internal Exception. The other, set_finished(), starts a threading.Timer that will set it after a delay (the settle_time). One of these methods may be called, and at most once. If one is called twice or if both are called, InvalidState is raised. If they are called too late to prevent a StatusTimeoutError, they are ignored but one call is still allowed. Thus, an external callback, e.g. pyepics, may reports success or failure after the Status object has expired, but to no effect because the callbacks have already been called and the program has moved on.

__init__(*, timeout=None, settle_time=0, done=None, success=None)

Methods

__init__(*[, timeout, settle_time, done, ...])
add_callback(callback)	Register a callback to be called once when the Status finishes.
exception([timeout])	Return the exception raised by the action.
set_exception(exc)	Mark as finished but failed with the given Exception.
set_finished()	Mark as finished successfully.
wait([timeout])	Block until the action completes.

Attributes

callbacks	Callbacks to be run when the status is marked as finished
done	Boolean indicating whether associated operation has completed.
finished_cb
settle_time	A delay between when set_finished() is when the Status is done.
success	Boolean indicating whether associated operation has completed.
timeout	The timeout for this action.