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 : 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.
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.
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.
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_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.
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_index : int

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_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 : pathlib.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_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.
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.
Raises:
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.
Returns:
script_info : ScriptInfo

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.
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.
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 [ScriptInfo]

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.
Raises:
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.
Returns:
info_list : list [ScriptInfo]

List of all scripts that were terminated.