SalInfo

class lsst.ts.salobj.SalInfo(domain, name, index=0)

Bases: object

DDS information for one SAL component and its DDS partition

Parameters:

domain : Domain

DDS domain participant and quality of service information.

name : str

SAL component name.

index : int, optional

Component index; 0 or None if this component is not indexed.

Raises:

RuntimeError

If environment variable LSST_DDS_PARTITION_PREFIX is not defined.

RuntimeError

If the IDL file cannot be found for the specified name.

TypeError

If domain is not a Domain.

ValueError

If index is nonzero and the component is not indexed.

Notes

Reads the following Environment Variables; follow the link for details:

• LSST_DDS_PARTITION_PREFIX (required): the DDS partition name.
• LSST_DDS_HISTORYSYNC, optional: time limit (sec) for waiting for historical (late-joiner) data.

Usage

Call start after constructing this SalInfo and all Remote objects. Until start is called no data will be read.

Each SalInfo automatically registers itself with the specified domain for cleanup using a weak reference to avoid circular dependencies. You may safely close a SalInfo before closing its domain, and this is recommended if you create and destroy many remotes.

DDS Partition Names

The DDS partition name for each topic is {prefix}.{name}.{suffix}, where:

• prefix = $LSST_DDS_PARTITION_PREFIX (fall back to $LSST_DDS_DOMAIN if necessary).
• name = the name constructor argument.
• suffix = “cmd” for command topics, and “data” for all other topics, including ackcmd.

The idea is that each Remote and Controller should have just one subscriber and one publisher, and that the durability service for a Controller will not read topics that a controller writes: events, telemetry, and the ackcmd topic.

Attributes:

domain : Domain

The domain constructor argument.

name : str

The name constructor argument.

index : int

The index constructor argument.

indexed : bool

True if this SAL component is indexed (meaning a non-zero index is allowed), False if not.

identity : str

Value used for the private_identity field of DDS messages. Defaults to username@host, but CSCs should use the CSC name: * SAL_component_name for a non-indexed SAL component * SAL_component_name:index for an indexed SAL component.

isopen : bool

Is this read topic open? True until close is called.

log : logging.Logger

A logger.

partition_prefix : str

The DDS partition name prefix, from environment variable LSST_DDS_PARTITION_PREFIX.

publisher : dds.Publisher

A DDS publisher, used to create DDS writers.

subscriber : dds.Subscriber

A DDS subscriber, used to create DDS readers.

start_task : asyncio.Task

A task which is finished when start is done, or to an exception if start fails.

done_task : asyncio.Task

A task which is finished when close is done.

command_names : List [str]

A tuple of command names without the "command_" prefix.

event_names : List [str]

A tuple of event names, without the "logevent_" prefix

telemetry_names : List [str]

A tuple of telemetry topic names.

sal_topic_names : List [str]

A tuple of SAL topic names, e.g. “logevent_summaryState”, in alphabetical order.

revnames : dict [str, str]

A dict of topic name: name_revision.

topic_info : dict [str, TopicMetadata]

A dict of SAL topic name: topic metadata.

authorized_users : List [str]

Set of users authorized to command this component.

non_authorized_cscs : List [str]

Set of CSCs that are not authorized to command this component.

Attributes Summary

AckCmdType	The class of command acknowledgement.
cmd_partition_name	Partition name for command topics.
cmd_publisher	Publisher for command topics, but not ackcmd.
cmd_subscriber	Subscriber for command topics, but not ackcmd.
data_partition_name	Partition name for non-command topics.
data_publisher	Publisher for ackcmd, events and telemetry topics.
data_subscriber	Subscriber for ackcmd, events and telemetry topics.
name_index	Get name[:index].
started	Return True if successfully started, False otherwise.

Methods Summary

add_reader(topic)	Add a ReadTopic, so it can be read by the read loop and closed by close.
add_writer(topic)	Add a WriteTopic, so it can be closed by close.
assert_started()	Raise RuntimeError if not successfully started.
close()	Shut down and clean up resources.
makeAckCmd(*args, **kwargs)	Deprecated version of make_ackcmd.
make_ackcmd(private_seqNum, ack[, error, …])	Make an AckCmdType object from keyword arguments.
parse_metadata()	Parse the IDL metadata to generate some attributes.
start()	Start the read loop.

Attributes Documentation

AckCmdType

The class of command acknowledgement.

It includes these fields, as well as the usual other private fields.

private_seqNum : int

Sequence number of command.

ack : int

Acknowledgement code; one of the SalRetCode CMD_ constants, such as SalRetCode.CMD_COMPLETE.

error : int

Error code; 0 for no error.

result : str

Explanatory message, or “” for no message.

Raises:

RuntimeError

If the SAL component has no commands (because if there are no commands then there is no ackcmd topic).

cmd_partition_name

Partition name for command topics.

cmd_publisher

Publisher for command topics, but not ackcmd.

This has a different partition name than a data_publisher.

cmd_subscriber

Subscriber for command topics, but not ackcmd.

This has a different partition name than a data_subscriber.

data_partition_name

Partition name for non-command topics.

data_publisher

Publisher for ackcmd, events and telemetry topics.

This has a different partition name than a cmd_publisher.

data_subscriber

Subscriber for ackcmd, events and telemetry topics.

This has a different partition name than a cmd_subscriber.

name_index

Get name[:index].

The suffix is only present if the component is indexed.

started

Return True if successfully started, False otherwise.

Methods Documentation

add_reader(topic)

Add a ReadTopic, so it can be read by the read loop and closed by close.

Parameters:

topic : topics.ReadTopic

Topic to read and (eventually) close.

Raises:

RuntimeError

If called after start has been called.

add_writer(topic)

Add a WriteTopic, so it can be closed by close.

Parameters:

topic : topics.WriteTopic

Write topic to (eventually) close.

assert_started()

Raise RuntimeError if not successfully started.

Notes

Does not raise after this is closed. That avoids race conditions at shutdown.

close()

Shut down and clean up resources.

May be called multiple times. The first call closes the SalInfo; subsequent calls wait until the SalInfo is closed.

makeAckCmd(*args, **kwargs)

Deprecated version of make_ackcmd.

make_ackcmd(private_seqNum, ack, error=0, result='', timeout=0, truncate_result=False)

Make an AckCmdType object from keyword arguments.

Parameters:

private_seqNum : int

Sequence number of command.

ack : int

Acknowledgement code; one of the salobj.SalRetCode.CMD_ constants, such as salobj.SalRetCode.CMD_COMPLETE.

error : int

Error code. Should be 0 unless ack is salobj.SalRetCode.CMD_FAILED

result : str

More information. This is arbitrary, but limited to MAX_RESULT_LEN characters.

timeout : float

Esimated command duration. This should be specified if ack is salobj.SalRetCode.CMD_INPROGRESS.

truncate_result : bool

What to do if result is longer than MAX_RESULT_LEN characters:

• If True then silently truncate result to MAX_RESULT_LEN characters.
• If False then raise ValueError

Raises:

ValueError

If len(result) > `MAX_RESULT_LEN and truncate_result is false.

RuntimeError

If the SAL component has no commands (because if there are no commands then there is no ackcmd topic).

parse_metadata()

Parse the IDL metadata to generate some attributes.

Set the following attributes (see the class doc string for details):

• indexed
• command_names
• event_names
• telemetry_names
• sal_topic_names
• revnames

start()

Start the read loop.

Call this after all topics have been added.

Raises:

RuntimeError

If start has already been called.