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.

Notes

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

  • LSST_DDS_ENABLE_AUTHLIST (optional): if set to “1” enable authlist-based command authorization. If “0” or undefined, do not enable authorization.

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

authorized_usersList [str]

Set of users authorized to command this component.

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

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.