Status#

Status object.

The Status class has been adapted from ophyd. The ophyd license is reproduced below:

Copyright (c) 2014, Brookhaven Science Associates, Brookhaven National Laboratory. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  • Neither the name of the Brookhaven Science Associates, Brookhaven National Laboratory nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

class sunflare.engine.status.Status(*, timeout=None, settle_time=0)#

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

add_callback(callback)#

Register a callback to be called once when the Status finishes.

The callback will be called exactly once. If the Status is finished before a callback is added, it will be called immediately. This is threadsafe. The callback will be called regardless of success of failure. The callback has access to this status object, so it can distinguish success or failure by inspecting the object.

Parameters:

callback (callable) – Expected signature: callback(status).

Return type:

None

property callbacks: deque[Callable[[Status], None]]#

Callbacks to be run when the status is marked as finished.

property done: bool#

Boolean indicating whether associated operation has completed.

This is set to True at __init__ time or by calling set_finished(), set_exception(). Once True, it can never become False.

exception(timeout=None)#

Return the exception raised by the action.

If the action has completed successfully, return None. If it has finished in error, return the exception.

Parameters:

timeout (Union[Number, None], optional) – If None (default) wait indefinitely until the status finishes.

Returns:

The exception raised by the action. If the action has completed successfully, return None.

Return type:

Exception

Raises:

WaitTimeoutError – If the status has not completed within timeout (starting from when this method was called, not from the beginning of the action).

set_exception(exc)#

Mark as finished but failed with the given Exception.

This method should generally not be called by the recipient of this Status object, but only by the object that created and returned it.

Parameters:

exc (Exception)

Return type:

None

set_finished()#

Mark as finished successfully.

This method should generally not be called by the recipient of this Status object, but only by the object that created and returned it.

Return type:

None

property settle_time: float#

A delay between when set_finished() is when the Status is done.

This is set when the Status is created, and it cannot be changed.

property success: bool#

Boolean indicating whether associated operation has completed.

This is set to True at __init__ time or by calling set_finished(), set_exception() . Once True, it can never become False.

property timeout: float | None#

The timeout for this action.

This is set when the Status is created, and it cannot be changed.

wait(timeout=None)#

Block until the action completes.

When the action has finished succesfully, return None. If the action has failed, raise the exception.

Parameters:

timeout (float, optional) – If None (default) wait indefinitely until the status finishes.

Raises:

  • WaitTimeoutError – If the status has not completed within timeout (starting from when this method was called, not from the beginning of the action).

  • StatusTimeoutError – If the status has failed because the timeout that it was initialized with has expired.

  • Exception – This is status.exception(), raised if the status has finished with an error. This may include TimeoutError, which indicates that the action itself raised TimeoutError, distinct from WaitTimeoutError above.

Return type:

None