Subscribe And Poll

For high-performance continuous or block streaming data

The subscribe and poll mechanism is based on the update message that the device sends for every node change. A client can subscribe to the changes of one or more nodes.

This tells the Data Server to create a buffer for each subscribed node and to buffer each update message received for the subscribed nodes. The user can then call poll (in the same API session) to transfer the data from the Data Server's buffers to the API's client code.

Warning

If poll is not called within 5 seconds, the Data Server clears its buffers for the subscribed nodes and starts accumulating data again. This means that for continuous transfer of data, the user must regularly poll data from the Data Server to ensure that no data is lost in between polls.

The subscribe and poll is one of the most powerful low level commands. It primary use case is to retrieve streaming data, e.g demodulator samples, without any sample loss from a connected device. But is also can be used to stay updated on the value change of a setting node. It is for example used by the LabOne UI to ensure that the displayed settings are always up-to-date.

For streaming data the data returned is the discrete device data as sampled or calculated by the digital signal processing algorithms on the instrument.

Warning

The data from multiple nodes may not be aligned due to different sampling rates or different streaming node sources. Therefore the LabOne Modules often provide an easier and more efficient choice for data acquisition than the comparably low-level poll command.

Note

The Data Server continues to accumulate new data sent from the device for the subscribed nodes after polling and will continue to do so until unsubscribe is called for that node. It is good practice to call unsubscribe on the nodes when you no longer want to poll data from them so that the Data Server stops accumulating data and can free up the system's memory.

Ensure synchronization of settings before streaming data (sync)

To ensure that any settings have taken effect on the instrument before streaming data is processed, a special sync command is provided which ensures that the API blocks during the full command execution of sending down a marker to the device and receiving it again over the API. During

that time all buffers are cleaned. Therefore, after the sync command the newly recorded poll data will be later in time than the previous set commands. Be aware that this command is quite expensive ~100ms. It also is a global operation and the marker is send to all connected devices and can cause unwanted side effects. The sync command should therefore only be used with care.

Manually trigger an update Event

By using the poll command, one can stay informed about every update message for all subscribed nodes. As already explained, the device sends an update message for every node value change (or every new sample in case of a streaming node). The LabOne API also offers a way to trigger an update message even though the value did not change. This command is called getAsEvent.

The data server automatically stores the update message in the client buffer. This does not require a subscription to the node itself. With the next poll command the client receives the update message automatically.