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 (str, bytes or os.PathLike) – Path to standard SAL scripts.

  • externalpath (str, bytes or os.PathLike) – Path to external SAL scripts.

  • next_visit_callback (coroutine (optional)) – Coroutine 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 (coroutine (optional)) – Coroutine to call when a script loses its group ID. It receives one argument: a ScriptInfo with group_id not yet cleared.

  • queue_callback (coroutine (optional)) – Coroutine to call when the queue state changes. It receives no arguments.

  • script_callback (coroutine (optional)) – Coroutine 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.

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 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_enable(enabled)

Set enabled state.

set_group_id(script_info)

Set or clear the group ID for a script.

set_running(run)

Set running state.

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 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, start_block=False, block_size=0)#

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.

  • start_block (bool, optional) – Start a new block? Default=False.

  • block_size (int, optional) – How many scripts are part of this block? Default=0

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.

Return type:

None

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

Return type:

None

async close()#

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

Return type:

None

find_available_scripts()#

Find available scripts.

Returns:

scripts – Paths to standard and external scripts.

Return type:

Scripts

get_queue_index(sal_index)#

Get queue index of a script on the queue.

Parameters:

sal_index (int) – SAL index of script.

Raises:

ValueError – If the script cannot be found on the queue.

Return type:

int

get_script_info(sal_index, search_history)#

Get information about a script.

Search current script, the queue and history.

Parameters:

  • sal_index (int) – SAL index of script.

  • search_history (bool) – Search past history? If False will only look for the current and queued scripts.

Returns:

Script info for the requested sal index.

Return type:

ScriptInfo

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_standard (bool) – Is this a standard (True) or external (False) script?

  • path (str, bytes or os.PathLike) – Path to script, relative to standard or external root dir.

Returns:

fullpath – The full path to the script.

Return type:

pathlib.Path

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.

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

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.

Return type:

None

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”

Return type:

str

pop_script_info(sal_index)#

Remove and return information about a script on the queue.

Parameters:

sal_index (int) – SAL index of script.

Returns:

Script infor of the removed script.

Return type:

ScriptInfo

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:

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

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.

Returns:

script_info – Info for the requeued script.

Return type:

ScriptInfo

async set_enable(enabled)#

Set enabled state.

Parameters:

enabled (bool)

Return type:

None

async set_group_id(script_info)#

Set or clear the group ID for a script.

Parameters:

script_info (ScriptInfo) – Script info.

Raises:

RuntimeError – If the group ID cannot be set.

Return type:

None

async set_running(run)#

Set running state.

Parameters:

run (bool)

Return type:

None

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_info (ScriptInfo) – Script info for script stop.

Return type:

None

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_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?

Return type:

None

async terminate_all()#

Terminate all scripts and return info for the ones terminated.

Returns:

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

Return type:

list [ScriptInfo]

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_info (ScriptInfo) – Script info for script terminate.

Raises:

ValueError – If a script is not queued or running.

Return type:

None