# QueueModel¶

class lsst.ts.scriptqueue.QueueModel(domain, log, standardpath, externalpath, next_visit_callback=None, next_visit_canceled_callback=None, queue_callback=None, script_callback=None, min_sal_index=1000, max_sal_index=2147483647, verbose=False)

Bases: object

Code to load and configure scripts; implementation for ScriptQueue.

Parameters: domain : salobj.lsst.ts.salobj.Domain DDS domain; typically ScriptQueue.domain log : logging.Logger Parent logger. standardpath : Path to standard SAL scripts. externalpath : Path to external SAL scripts. next_visit_callback : callable (optional) Function to call when a script gets a new group ID. It receives one argument: a ScriptInfo. This is separate from script_callback to make it easier to output the nextVisit event. next_visit_canceled_callback : callable (optional) Function to call when a script loses its group ID. It receives one argument: a ScriptInfo with group_id not yet cleared. queue_callback : callable (optional) Function to call when the queue state changes. It receives no arguments. script_callback : callable (optional) Function to call when information about a script changes. It receives one argument: a ScriptInfo. This is not called if the only change is to the group ID; see next_visit_callback and next_visit_canceled_callback for that. min_sal_index : int (optional) Minimum SAL index for Script SAL components max_sal_index : int (optional) Maximum SAL index for Script SAL components verbose : bool (optional) If True then print log messages from scripts to stdout. ValueError If standardpath or externalpath does not exist.

Attributes Summary

 current_index SAL index of the current script, or 0 if none. enabled Get or set enabled state. history_indices SAL indices of scripts on the history queue. next_sal_index Get the next available SAL Script index. queue_indices SAL indices of scripts on the queue. running Get or set running state.

Methods Summary

 add(script_info, location, location_sal_index) Add a script to the queue. clear_group_id(script_info, command_script) Clear the group ID of the specified script, if appropriate. close() Shut down the queue, terminate all scripts and free resources. find_available_scripts() Find available scripts. get_queue_index(sal_index) Get queue index of a script on the queue. get_script_info(sal_index, search_history) Get information about a script. make_full_path(is_standard, path) Make a full path from path and is_standard and check that it points to a runnable script. move(sal_index, location, location_sal_index) Move a script within the queue. next_group_id() Get the next group ID. pop_script_info(sal_index) Remove and return information about a script on the queue. requeue(sal_index, seq_num, location, …) Requeue a script. set_group_id(script_info) Set or clear the group ID for a script. stop_one_script(script_info) Stop a queued or running script, giving it time to clean up. stop_scripts(sal_indices, terminate) Stop one or more queued scripts and/or the current script. terminate_all() Terminate all scripts and return info for the ones terminated. terminate_one_script(script_info) Terminate a queued or running script. wait_terminate_all([timeout]) Awaitable version of terminate_all.

Attributes Documentation

current_index

SAL index of the current script, or 0 if none.

enabled

Get or set enabled state.

True if ScriptQueue is in the enabled state, False otherwise.

history_indices

SAL indices of scripts on the history queue.

next_sal_index

Get the next available SAL Script index.

queue_indices

SAL indices of scripts on the queue.

running

Get or set running state.

If set False the queue pauses.

Methods Documentation

add(script_info, location, location_sal_index)

Add a script to the queue.

Launch the script in a new subprocess and wait for the subprocess to start. Start a background task to configure the script when it is ready.

Parameters: script_info : ScriptInfo Script info. location : Location Location of script. location_sal_index : int SAL index of script that location is relative to. ValueError If the script does not exist or is not executable. ValueError If location is not one of the supported enum values. ValueError If location is relative and a script at location_sal_index is not queued.
clear_group_id(script_info, command_script)

Clear the group ID of the specified script, if appropriate.

Clear the group ID of the specified script if the group ID is set or is being set.

Parameters: script_info : ScriptInfo Script info. command_script : bool If True then issue the setGroupId command to the script (in the background). The only time you would set this False is if you are about to terminate the script.
close()

Shut down the queue, terminate all scripts and free resources.

find_available_scripts()

Find available scripts.

Returns: scripts : Scripts Paths to standard and external scripts.
get_queue_index(sal_index)

Get queue index of a script on the queue.

Parameters: sal_index : int SAL index of script. ValueError If the script cannot be found on the queue.
get_script_info(sal_index, search_history)

Search current script, the queue and history.

Parameters: sal_index : int SAL index of script. ValueError If the script cannot be found.
make_full_path(is_standard, path)

Make a full path from path and is_standard and check that it points to a runnable script.

Parameters: is_standard : bool Is this a standard (True) or external (False) script? path : Path to script, relative to standard or external root dir. fullpath : pathlib.Path The full path to the script. ValueError If The full path is not in the appropriate root path (standardpath or externalpath, depending on is_standard). ValueError If the script does not exist or is not a file, is invisible (name starts with “.”) or private (name starts with “_”), or is not executable.
move(sal_index, location, location_sal_index)

Move a script within the queue.

Parameters: sal_index : int SAL index of script to move. location : Location Location of script. location_sal_index : int SAL index of script that location is relative to. ValueError If the script is not queued. ValueError If location is not one of the supported enum values. ValueError If location is relative and a script at location_sal_index is not queued.
static next_group_id()

Get the next group ID.

The group ID is the current TAI date and time as a string in ISO format. It has T separating date and time and no time zone suffix. Here is an example: “2020-01-17T22:59:05.721”

pop_script_info(sal_index)

Remove and return information about a script on the queue.

Parameters: sal_index : int SAL index of script. ValueError If the script cannot be found on the queue.
requeue(sal_index, seq_num, location, location_sal_index)

Requeue a script.

Add a script that is a copy of an existing script, including the same configuration.

Launch the script in a new subprocess and wait for the subprocess to start. Start a background task to configure the script when it is ready.

Parameters: domain : lsst.ts.salobj.Domain DDS domain. sal_index : int SAL index of script to requeue. seq_num : int Command sequence number; recorded in the script info. location : Location Location of script. location_sal_index : int SAL index of script that location is relative to. script_info : ScriptInfo Info for the requeued script. ValueError If the script sal_index cannot be found. ValueError If location is not one of the supported enum values. ValueError If location is relative and a script location_sal_index is not queued.
set_group_id(script_info)

Set or clear the group ID for a script.

Parameters: script_info : ScriptInfo Script info. RuntimeError If the group ID cannot be set.
stop_one_script(script_info)

Stop a queued or running script, giving it time to clean up.

First send the script the stop command, giving that timeout a few seconds to succeed or fail. If necessary, terminate the script by sending SIGTERM to the process.

This is slower and than terminate, but gives the script a chance to clean up. If successful, the script is removed from the queue.

Parameters: script_info : ScriptInfo Script info for script stop.
stop_scripts(sal_indices, terminate)

Stop one or more queued scripts and/or the current script.

Silently ignores scripts that cannot be found or are already stopped.

Parameters: sal_indices : iterable of int SAL indices of scripts to stop. Scripts whose indices are not found are ignored. terminate : bool Terminate a running script instead of giving it time to stop gently?
terminate_all()

Terminate all scripts and return info for the ones terminated.

Does not wait for termination to actually finish. See also wait_terminate_all.

Returns: info_list : List of all scripts that were terminated.
terminate_one_script(script_info)

Terminate a queued or running script.

If successful (as it will be, unless the script catches SIGTERM), the script is removed from the the queue. If you have time please try stop first, as that gives the script a chance to clean up. If stop fails then the script will still be terminated.

Parameters: script_info : ScriptInfo Script info for script terminate. ValueError If a script is not queued or running.
wait_terminate_all(timeout=10)

Awaitable version of terminate_all.

Parameters: timeout : float Timeout waiting for the process tasks to terminate. info_list : List of all scripts that were terminated.