RemoteEvent

class lsst.ts.salobj.topics.RemoteEvent(salinfo: SalInfo, name: str, max_history: int = 1, queue_len: int = 100)

Bases: ReadTopic

Read a specific event topic.

Parameters:
salinfoSalInfo

SAL component information.

namestr

Event name with no prefix, e.g. “summaryState”.

max_historyint, optional

Maximum number of historical items to read. 1 is typical.

queue_lenint, optional

Number of elements that can be queued for get_oldest.

Attributes Summary

DataType

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

allow_multiple_callbacks

Can callbacks can run simultaneously?

attr_name

Get the salobj topic attribute name, e.g.

callback

Asynchronous 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

nqueued

Return the number of messages in the Python queue.

sal_name

Get the SAL topic name, e.g.

Methods Summary

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()

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(*, flush[, timeout])

Pop and return the oldest message from the queue, waiting for data if the queue is empty.

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 set data and write a message for a topic is:

  • RemoteCommand.set_start to start a command.

  • CommandEvent.set_write to write an event.

  • CommandTelemetry.set_write to write a telemetry message.

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.

attr_name

Get the salobj topic attribute name, e.g. evt_summaryState.

callback

Asynchronous callback function, or None if there is not one.

Synchronous callback functions are deprecated.

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

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
nqueued

Return the number of messages in the Python queue.

sal_name

Get the SAL topic name, e.g. logevent_summaryState.

Methods Documentation

async aget(timeout: float | None = None) BaseMsgType

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:
timeoutfloat, optional

Time limit, in seconds. If None then no time limit.

Returns:
dataDataType

The current or next message.

Raises:
asyncio.TimeoutError

If no message is available within the specified time limit.

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() None

A synchronous and possibly less thorough version of close.

Intended for exit handlers and constructor error handlers.

async close() None

Shut down and release resources.

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

flush() None

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() BaseMsgType | 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, get_oldest, and next.

Returns:
dataself.DataType or None

Return self.data if data has been read, else None.

Raises:
RuntimeError

If the salinfo has not started reading.

get_oldest() BaseMsgType | None

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:
dataself.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.

async next(*, flush: bool, timeout: float | None = None) BaseMsgType

Pop and return the oldest message from the queue, waiting for data if the queue is empty.

This method affects the data returned by get_oldest, but not the data returned by aget or get.

Parameters:
flushbool

If True then flush the queue before starting a read. This guarantees that the method will wait for a new message. If False and there is data on the queue, then pop and return the oldest message from the queue, without waiting; if queue is empty then wait for a new message.

timeoutfloat, optional

Time limit, in seconds. If None then no time limit.

Returns:
dataDataType

The message data.

Raises:
asyncio.TimeoutError

If no message is available within the specified time limit.

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