Long Running Command Decorators

Decorators for working with long running commands.

ska_tango_base.long_running_commands.decorators.long_running_command(*, fisallowed: Callable[[...], bool] | str | None = None, **cmd_kwargs: Any) → Callable[[Callable[[...], Callable[[...], Any]]], Callable[[...], tuple[list[ResultCode], list[str]]]]

ska_tango_base.long_running_commands.decorators.long_running_command(task_factory: Callable[[...], Callable[[...], Any]], *, fisallowed: Callable[[...], bool] | str | None = None, **cmd_kwargs: Any) → Callable[[...], tuple[list[ResultCode], list[str]]]

Mark a method as a long running command.

Wraps a method that returns a task with common boilerplate code for a long running command and submits the task to the task executor of the device. The wrapped task factory MUST be a method in a class that inherits from LRCMixin.

The fisallowed parameter expects a device class method with a keyword argument request_type that defaults to LRCReqType.ENQUEUE_REQ, or the name of such a method available on the device. The method will be called at submission time with the default keyword argument and will be called at execution time request_type=LRCReqType.EXECUTE_REQ. The function is expected to return False, if the task cannot be enqueued or executed. Alternatively, fisallowed may raise an exception to provide a more detailed error message.

If fisallowed is not provided, then the default method name of “is_<cmd>_allowed” will be looked up on the device. If this is not found, then it will be assumed that the task can awalys be enqueued and executed.

Parameters:

• task_factory – An LRCMixin subclass method that returns a task.

• fisallowed – Whether the task is allowed to execute. Called when command is added to the LRC queue (ENQUEUE_REQ) and immediately before execution (EXECUTE_REQ).

• cmd_kwargs – Passed on to the tango.server.command call.

Returns:

A Tango command that submits the task to the long running command queue.

ska_tango_base.long_running_commands.decorators.submit_lrc_task(*, cmd_name: str | None = None, fisallowed: Callable[[...], bool] | str | None = None, started_callback: Callable[[...], None] | str | None = None, completed_callback: Callable[[...], None] | str | None = None) → Callable[[Callable[[...], Callable[[...], Any]]], Callable[[...], tuple[list[ResultCode], list[str]]]]

ska_tango_base.long_running_commands.decorators.submit_lrc_task(task_factory: Callable[[...], Callable[[...], Any]], *, cmd_name: str | None = None, fisallowed: Callable[[...], bool] | str | None = None, started_callback: Callable[[...], None] | str | None = None, completed_callback: Callable[[...], None] | str | None = None) → Callable[[...], tuple[list[ResultCode], list[str]]]

Submit a task returned by task_factory to the TaskExecutor.

Wraps a method that returns a task with common boilerplate code for a long running command and submits the task to the task executor of the device. The wrapped task factory MUST be a method in a class that inherits from LRCMixin.

The fisallowed parameter expects a device class method with a keyword argument request_type that defaults to LRCReqType.ENQUEUE_REQ, or the name of such a method available on the device. The method will be called at submission time with the default keyword argument and will be called at execution time request_type=LRCReqType.EXECUTE_REQ. The function is expected to return False, if the task cannot be enqueued or executed. Alternatively, fisallowed may raise an exception to provide a more detailed error message.

If fisallowed is not provided, then the default method name of “is_<cmd>_allowed” will be looked up on the device. If this is not found, then it will be assumed that the task can always be enqueued and executed.

Parameters:

• task_factory – An LRCMixin subclass method that returns a task.

• fisallowed – Whether the task is allowed to execute. Called when command is added to the LRC queue (ENQUEUE_REQ) and immediately before execution (EXECUTE_REQ).

• started_callback – Callback passed to the command tracker that is called when the command transitions to IN_PROGRESS status.

• completed_callback – Callback passed to the command tracker that is called when the command transitions to COMPLETED status.

Returns:

The wrapped function

ska_tango_base.long_running_commands.decorators.mark_long_running(fn: Any) → Any

Mark a executing_<Cmd>() method as a long running command.

This is used by the default is_<Cmd>_allowed() methods to know that they should not check the state machine when the Tango command is initially called and instead wait for the is_<Cmd>_allowed() method to be called later with LRCReqType.EXECUTE_REQ when the task is about to be executed.

Warning

This decorator does not arrange for the is_<Cmd>_allowed() method to be called with LRCReqType.EXECUTE_REQ. For this use the submit_lrc_task() decorator or submit_lrc_task().