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_DOMAIN 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_DOMAIN (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.

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.

isopen : bool

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

log : logging.Logger

A logger.

partition_name : str

The DDS partition name, from environment variable LSST_DDS_DOMAIN.

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.

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.

Attributes Summary

AckCmdType The class of command acknowledgement.
idl_loc Path to the IDL file for this SAL component; a pathlib.Path.

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.
close() Shut down and clean up resources.
makeAckCmd(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).
idl_loc

Path to the IDL file for this SAL component; a pathlib.Path.

Deprecated; use metadata.idl_path instead.

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.
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(private_seqNum, ack, error=0, result='', 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.

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.