SalInfo¶

class lsst.ts.salobj.SalInfo(domain: Domain, name: str, index: int | None = 0, write_only: bool = False)¶

Bases: object

DDS information for one SAL component and its DDS partition

Parameters:

domainDomain: DDS domain participant and quality of service information.
namestr: SAL component name.
indexint, optional: Component index; 0 or None if this component is not indexed.
write_onlybool: If false this SalInfo will not subscribe to any topics.

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 an instance of Domain or if index is not an int, enum.IntEnum, or None.
ValueError: If index is nonzero and the component is not indexed.

Attributes:

domainDomain: The domain constructor argument.
namestr: The name constructor argument.
indexint: The index constructor argument.
indexedbool: True if this SAL component is indexed (meaning a non-zero index is allowed), False if not.
identitystr: 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.
loglogging.Logger: A logger.
partition_prefixstr: The DDS partition name prefix, from environment variable LSST_DDS_PARTITION_PREFIX.
publisherdds.Publisher: A DDS publisher, used to create DDS writers.
subscriberdds.Subscriber: A DDS subscriber, used to create DDS readers.
isopenbool: Is this instance open? True until close or basic_close is called. This instance is fully closed when done_task is done.
start_calledbool: Has the start method been called? This instance is fully started when start_task is done.
done_taskasyncio.Task: A task which is finished when close or basic_close is done.
start_taskasyncio.Task: A task which is finished when start is done, or to an exception if start fails.
command_namesList [str]: A tuple of command names without the "command_" prefix.
event_namesList [str]: A tuple of event names, without the "logevent_" prefix
telemetry_namesList [str]: A tuple of telemetry topic names.
sal_topic_namesList [str]: A tuple of SAL topic names, e.g. “logevent_summaryState”, in alphabetical order.
revnamesdict [str, str]: A dict of topic name: name_revision.
topic_infodict [str, TopicMetadata]: A dict of SAL topic name: topic metadata.
Notes
—–
Reads the following `Environment Variables
<https://ts-salobj.lsst.io/configuration.html#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**
* Construct a `SalInfo` object for a particular SAL component and index.
* Use the object to construct all topics (subclasses of `topics.BaseTopic`): that you want to use with this SAL component and index.
* Call `start`.
* When you are finished, call `close`, or at least be sure to close: the domain when you are finished with all classes that use it (see Cleanup below).
You cannot read topics constructed with a `SalInfo` object
until you call `start`, and once you call `start`, you cannot
use the `SalInfo` object to construct any more topics.
You may use `SalInfo` as an async context manager, but this is primarily
useful for cleanup. After you enter the context (create the object)
you will still have to create topics and call start.
This is different from `Domain`, `Controller`, and `Remote`,
which are ready to use when you enter the context.
**Cleanup**
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.
In any case, be sure to close the ``domain`` when you are done.
**DDS Partition Names**
The DDS partition name for each topic is {prefix}.{name}.{suffix}, where:
* ``prefix`` = $LSST_DDS_PARTITION_PREFIX.
* ``name`` = the ``name`` constructor argument.
* ``suffix`` = “cmd” for command topics, and “data” for all other topics,: including ackcmd.
The idea is that each `Controller` and `Remote` should have just one
subscriber and one publisher, and that the durability service
will only read topics that the object reads, not topics that it writes.
Thus the durability service for `Controller` will only read commands,
and the durability service for `Remote` will read everything but commands
(events, telemetry and the ``ackcmd`` topic).

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].
`running`	Return True if started and not closed.
`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.
`basic_close`()	A synchronous and less thorough version of `close`.
`close`()	Shut down and clean up resources.
`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_seqNumint: Sequence number of command.
ackint: Acknowledgement code; one of the SalRetCode CMD_ constants, such as SalRetCode.CMD_COMPLETE.
errorint: Error code; 0 for no error.
resultstr: 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.

running¶: Return True if started and not closed.

started¶: Return True if successfully started, False otherwise.

Methods Documentation

add_reader(topic: ReadTopic) → None¶

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

Parameters:

topictopics.ReadTopic: Topic to read and (eventually) close.

Raises:

RuntimeError: If called after start has been called.

add_writer(topic: WriteTopic) → None¶

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

Parameters:

topictopics.WriteTopic: Write topic to (eventually) close.

assert_started() → None¶

Raise RuntimeError if not successfully started.

Notes

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

basic_close() → None¶

A synchronous and less thorough version of close.

Intended for exit handlers and constructor error handlers.

async close() → None¶

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.

make_ackcmd(private_seqNum: int, ack: SalRetCode, error: int = 0, result: str = '', timeout: float = 0) → AckCmdDataType¶

Make an AckCmdType object from keyword arguments.

Parameters:

private_seqNumint: Sequence number of command.
ackint: Acknowledgement code; one of the salobj.SalRetCode.CMD_ constants, such as salobj.SalRetCode.CMD_COMPLETE.
errorint: Error code. Should be 0 unless ack is salobj.SalRetCode.CMD_FAILED
resultstr: More information.
timeoutfloat: Esimated command duration. This should be specified if ack is salobj.SalRetCode.CMD_INPROGRESS.

Raises:

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

parse_metadata() → None¶

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

async start() → None¶

Start the read loop.

Call this after all topics have been added.

Raises:

RuntimeError: If start or close have already been called.

Navigation

SalInfo¶