ControllerCommand

class lsst.ts.salobj.topics.ControllerCommand(salinfo, name, max_history=0, queue_len=100)

Bases: lsst.ts.salobj.topics.ReadTopic

Read a specified command topic.

Parameters:
salinfo : SalInfo

SAL component information

name : str

Command name

Notes

Each command must be acknowledged by writing an appropriate ackcmd message. If you use a callback function to process the command then this happens automatically. Otherwise you must call the ack method to acknowledge the command yourself, though an initial acknowledgement with ack=SalRetCode.CMD_ACK is always automatically sent when the command is read.

After the initial acknowledgement with ack=SalRetCode.CMD_ACK, automatic ackowledgement for callback functions works as follows:

  • If the callback function is a coroutine then acknowledge with ack=SalRetCode.CMD_INPROGRESS just before running the callback.
  • If the callback function returns None then send a final acknowledgement with ack=SalRetCode.CMD_COMPLETE.
  • If the callback function returns an acknowledgement (instance of SalInfo.AckType) instead of None, then send that as the final acknowledgement.
  • If the callback function raises asyncio.TimeoutError then send a final acknowledgement with ack=SalRetCode.CMD_TIMEOUT.
  • If the callback function raises asyncio.CancelledError then send a final acknowledgement with ack=SalRetCode.CMD_ABORTED.
  • If the callback function raises ExpectedError then send a final acknowledgement with ack=SalRetCode.CMD_FAILED and result=f"Failed: {exception}".
  • If the callback function raises any other Exception then do the same as ExpectedError and also log a traceback.

Attributes Summary

DataType The class of data for this topic.
allow_multiple_callbacks Can callbacks can run simultaneously?
callback Callback function, or None if there is not one.
has_callback Return True if there is a callback function.
has_data Has any data been seen for this topic?
max_history
metadata Get topic metadata as a TopicMetadata, if available, else None.

Methods Summary

ack(data, ackcmd) Acknowledge a command by writing a new state.
ackInProgress(data[, result]) Ackowledge this command as “in progress”.
aget([timeout]) Get the current value, if any, else wait for the next value.
close() Shut down and release resources.
flush() Flush the queue of unread data.
get([flush]) Get the most recently seen value, or None if no data ever seen.
get_oldest() Pop and return the oldest value from the queue, or None if the queue is empty.
next(*[, timeout]) Wait for data, returning old data if found.

Attributes Documentation

DataType

The class of data for this topic.

allow_multiple_callbacks

Can callbacks can run simultaneously?

Notes

Ignored for synchronous callbacks because those block while running. In particular, if the callback is synchronous but launches one or more background jobs then the number of those jobs cannot be limited by this class.

callback

Callback function, or None if there is not one.

The callback function is called when new data is received; it receives one argument: the data.

Raises:
TypeError

When setting a new callback if the callback is not None and is not callable.

Notes

The callback function can be synchronous or asynchronous (e.g. defined with async def).

Setting a callback flushes the queue, and it will remain empty as long as there is a callback.

get_oldest and next are prohibited if there is a callback function. Technically they could both work, but get_oldest would always return None and next would miss data if it arrived while waiting for something else. It seemed safer to just raise an exception.

has_callback

Return True if there is a callback function.

has_data

Has any data been seen for this topic?

max_history
metadata

Get topic metadata as a TopicMetadata, if available, else None.

Methods Documentation

ack(data, ackcmd)

Acknowledge a command by writing a new state.

Parameters:
data : DataType

Command data.

ackcmd : salobj.AckCmdType

Command acknowledgement.
ackInProgress(data, result='')

Ackowledge this command as “in progress”.

aget(timeout=None)

Get the current value, if any, else wait for the next value.

Parameters:
timeout : float (optional)

Time limit, in seconds. If None then no time limit.
Returns:
data : DataType

The current or next value.
Raises:
RuntimeError

If a callback function is present.

Notes

Do not modify the returned data. To make a copy that you can modify use copy.copy(value).

close()

Shut down and release resources.

Intended to be called by SalInfo.close(), since that tracks all topics.

flush()

Flush the queue of unread data.

Raises:
RuntimeError

If a callback function is present.
get(flush=True)

Get the most recently seen value, or None if no data ever seen.

Parameters:
flush : bool (optional)

Flush the queue? Defaults to True for backwards compatibility. This only affects the next value returned by next and is ignored if there is a callback function.
Returns:
data : self.DataType or None

Return self.data if data has been read, else None.
get_oldest()

Pop and return the oldest value from the queue, or None if the queue is empty.

Returns:
data : self.DataType or None

The oldest value found on the queue, if any, else None.
Raises:
RuntimeError

If a callback function is present.

Notes

Use with caution when mixing with next, since that also consumes data from the queue.

next(*, timeout=None)

Wait for data, returning old data if found.

Unlike RemoteEvent.next and RemoteTelemetry.next, the flush argument is not allowed; the only way to flush old commands is to call flush.

Parameters:
timeout : float (optional)

Time limit, in seconds. If None then no time limit.
Returns:
data : DataType

Command data.
Raises:
RuntimeError

If a callback function is present.

Notes

Do not modify the data or assume that it will be static. If you need a private copy, then copy it yourself.