ControllerCommand¶

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

Bases: lsst.ts.salobj.topics.ReadTopic

Read a specified command topic.

Parameters:	salinfo : `SalInfo` SAL component information name : `str` Command name queue_len : `int`, optional Number of elements that can be queued for `get_oldest`.

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 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. This is very unusual, but might be useful if the callback wants to exit early and leave some background task or thread processing the rest of the command.
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 type (class) for a message of 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 ever been seen for this topic?
`max_history`
`metadata`	Get topic metadata as a `TopicMetadata`, if available, else `None`.
`nqueued`	Return the number of messages in the Python queue.
`volatile`	Does this topic have volatile durability?

Methods Summary

`ack`(data, ackcmd)	Acknowledge a command by writing a new state.
`ackInProgress`(data[, result])	Deprecated version of ack_in_progress.
`ack_in_progress`(data, *, timeout[, result])	Ackowledge this command as “in progress”.
`aget`([timeout])	Get the most recent message, or wait for data if no data has ever been seen (`has_data` False).
`basic_close`()	A synchronous and possibly less thorough version of `close`.
`close`()	Shut down and release resources.
`flush`()	Flush the queue used by `get_oldest` and `next`.
`get`([flush])	Get the most recent message, or `None` if no data has ever been seen (`has_data` False).
`get_oldest`()	Pop and return the oldest message from the queue, or `None` if the queue is empty.
`next`(*[, timeout])	Wait for data, returning old data if found.

Attributes Documentation

DataType¶

The type (class) for a message of this topic.

When you read or write a message for this topic you are reading or writing an instance of DataType.

Notes

The preferred way to write a message for a topic is:

RemoteCommand.set_start to start a command.
CommandEvent.set_put to write an event.
CommandTelemetry.set_put to write a telemetry message.

However, it is also possible to use DataType to create a message, then write, it as separate operations. For example, assuming we have a Remote for SAL component “Test”:

# The preferred way to issue a command:
await = remote.cmd_wait.set_put(duration=2, timeout=5)

# But an alternative is to first create the command,
# then send it, as two separate operations:
message = remote.cmd_wait.DataType(duration=2)
await remote.cmd_wait.start(message, timeout=5)

# Or, even more verbosely:
message = remote.cmd_wait.DataType()
message.duration = 2
await remote.cmd_wait.start(message, timeout=5)

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 a new message is received; it receives one argument: the message (an object of type topics.BaseTopic.DataType).

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 messages if they arrived while waiting for something else. It seems safer to raise an exception.

has_callback¶: Return True if there is a callback function.

has_data¶

Has any data ever been seen for this topic?

Raises:	RuntimeError If the `salinfo` has not started reading.

max_history¶

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

nqueued¶: Return the number of messages in the Python queue.

volatile¶: Does this topic have volatile durability?

Methods Documentation

ack(data, ackcmd)¶

Acknowledge a command by writing a new state.

Parameters:	data : `DataType` Data for the command being acknowledged. ackcmd : `salobj.AckCmdType` Command acknowledgement data.

ackInProgress(data, result='')¶: Deprecated version of ack_in_progress.

ack_in_progress(data, *, timeout, result='')¶

Ackowledge this command as “in progress”.

Parameters:	data : `DataType` Data for the command being acknowledged. timeout : `float` Estimated command duration (sec). result : `str`, optional Reason for acknowledgement. Typically left “”.

aget(timeout=None)¶

Get the most recent message, or wait for data if no data has ever been seen (has_data False).

This method does not change which message will be returned by any other method (except for the fact that new data will arrive while waiting).

Parameters:	timeout : `float`, optional Time limit, in seconds. If None then no time limit.
Returns:	data : `DataType` The current or next message.
Raises:	RuntimeError If a callback function is present, or if the `salinfo` has not started reading.

Notes

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

basic_close()¶

A synchronous and possibly less thorough version of close.

Intended for exit handlers and constructor error handlers.

close()¶

Shut down and release resources.

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

flush()¶

Flush the queue used by get_oldest and next.

This makes get_oldest return None and next wait, until a new message arrives. It does not change which message will be returned by aget or get.

Raises:	RuntimeError If a callback function is present.

get(flush=None)¶

Get the most recent message, or None if no data has ever been seen (has_data False).

This method does not change which message will be returned by aget. If flush=False this method also does not modify which message will be returned by get_oldest and next.

Parameters:	flush : `bool`, optional Flush the queue? Flushing the queue is deprecated and so is specifying this argument. False (the default) leaves the cache alone, which has no effect on the messages returned by any read method. True affects which messages will be returned by `get_oldest` and `next`. True has no effect if there is a callback function. Note: `None` is treated as `False`, but please do not specify it; it only supported for now to handle deprecation warnings..
Returns:	data : `self.DataType` or `None` Return `self.data` if data has been read, else `None`.
Raises:	RuntimeError If the `salinfo` has not started reading.

get_oldest()¶

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

This is a variant of next that does not wait for a new message. This method affects which message will be returned by next, but not which message will be returned by aget or get.

Returns:	data : `self.DataType` or `None` The oldest message found on the queue, if any, else `None`.
Raises:	RuntimeError If a callback function is present, or if the `salinfo` has not started reading.

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.

Navigation

ControllerCommand¶