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

domainsalobj.lsst.ts.salobj.Domain

DDS domain; typically ScriptQueue.domain

loglogging.Logger

Parent logger.

standardpathstr, bytes or os.PathLike

Path to standard SAL scripts.

externalpathstr, bytes or os.PathLike

Path to external SAL scripts.

next_visit_callbackcallable (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_callbackcallable (optional)

Function to call when a script loses its group ID. It receives one argument: a ScriptInfo with group_id not yet cleared.

queue_callbackcallable (optional)

Function to call when the queue state changes. It receives no arguments.

script_callbackcallable (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_indexint (optional)

Minimum SAL index for Script SAL components

max_sal_indexint (optional)

Maximum SAL index for Script SAL components

verbosebool (optional)

If True then print log messages from scripts to stdout.

Raises

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.

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

async 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_infoScriptInfo

Script info.

locationLocation

Location of script.

location_sal_indexint

SAL index of script that location is relative to.

Raises

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_infoScriptInfo

Script info.

command_scriptbool

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.

async close()

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

find_available_scripts()

Find available scripts.

Returns

scriptsScripts

Paths to standard and external scripts.

get_queue_index(sal_index)

Get queue index of a script on the queue.

Parameters

sal_indexint

SAL index of script.

Raises

ValueError

If the script cannot be found on the queue.

get_script_info(sal_index, search_history)

Get information about a script.

Search current script, the queue and history.

Parameters

sal_indexint

SAL index of script.

Raises

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_standardbool

Is this a standard (True) or external (False) script?

pathstr, bytes or os.PathLike

Path to script, relative to standard or external root dir.

Returns

fullpathpathlib.Path

The full path to the script.

Raises

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_indexint

SAL index of script to move.

locationLocation

Location of script.

location_sal_indexint

SAL index of script that location is relative to.

Raises

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_indexint

SAL index of script.

Raises

ValueError

If the script cannot be found on the queue.

async 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

domainlsst.ts.salobj.Domain

DDS domain.

sal_indexint

SAL index of script to requeue.

seq_numint

Command sequence number; recorded in the script info.

locationLocation

Location of script.

location_sal_indexint

SAL index of script that location is relative to.

Returns

script_infoScriptInfo

Info for the requeued script.

Raises

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.

async set_group_id(script_info)

Set or clear the group ID for a script.

Parameters

script_infoScriptInfo

Script info.

Raises

RuntimeError

If the group ID cannot be set.

async 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_infoScriptInfo

Script info for script stop.

async 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_indicesiterable of int

SAL indices of scripts to stop. Scripts whose indices are not found are ignored.

terminatebool

Terminate a running script instead of giving it time to stop gently?

async terminate_all()

Terminate all scripts and return info for the ones terminated.

Returns

info_listlist [ScriptInfo]

ScriptInfo for each terminated script. Excludes zombie script processes (which should be rare), because ScriptInfo is not available for those.

async 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_infoScriptInfo

Script info for script terminate.

Raises

ValueError

If a script is not queued or running.