Comparison of LabWindows/CVI Network Variable Connection Types

The LabWindows/CVI Network Variable Library provides a simple and robust mechanism to transfer data between programs running on one or more machines on a network. This mechanism involves the creation and use of “network variables” which are similar to program variables in that they contain data but their scope extends to the entire network. A network variable is hosted by the NI Variable Manager running on one particular machine. The variable is identified by a fully qualified name that is similar to a UNC path and consists of the hosting machine name, a process name, and a variable name. Network variables are not limited to LabWindows/CVI programs but can also be used in programs written in LabVIEW and Measurement Studio. The LabWindows/CVI Network Variable Library provides many different ways to connect to network variables. In this document, we will discuss these connection types and how and when to use them.

Network Variable Connection Types

The LabWindows/CVI Network Variable library provides the following ways to connect to a network variable:

• • Subscriber
  • Buffered Subscriber
  • Reader
  • Asynchronous Reader
  • Writer
  • Buffered Writer

The Subscriber, Buffered Subscriber, Reader, and Asynchronous Reader connections are used to read data from the variable. The Writer and Buffered Writer connections are used to write data to the variable.

Subscriber

The Subscriber connection is created by calling the CNVCreateSubscriber function. This connection is a subscription to the network variable which results in the user’s callback function getting called automatically when the value of the variable changes. See Figure 1. 

Figure 1: Network Variable Subscriber: The user’s callback function gets called automatically when the value of the network variable changes.

This is the most efficient connection to continuously read from the variable. The user callback is called on a separate library thread and this makes the data communication independent of other activities in the program. The callback function should return back to the library as soon as possible to let the library thread process and post further data updates. While the callback is running, new data updates cannot be posted and if there is more than one new update then all but the latest update will be lost. This connection type is appropriate when you want to continuously and automatically get the variable value, as and when it changes. 

Example Use Case: You would like to get the value from a variable as soon as it changes and chart it.

Buffered Subscriber

The Buffered Subscriber connection is created by calling the CNVCreateBufferedSubscriber function. This connection is a subscription to the network variable and results in the variable’s values getting sent and cached automatically in a local buffer. See Figure 2. 

Figure 2: Network Variable Buffered Subscriber: The network variable values are sent and cached automatically in a local buffer.

You specify the number of items that the buffer can hold when you create the connection. You can change this size later by calling the CNVSetConnectionAttribute function. You can read the values from the buffer on demand by calling the CNVGetDataFromBuffer function. If the network variable’s value changes rapidly and you do not read frequently from the local buffer, then the buffer may fill-up and overflow. In this case, the older data items are lost, and this condition is indicated by the Data Status output parameter of the CNVGetDataFromBuffer function. This parameter also indicates if the buffer is empty, i.e. no value is available, or if the returned data is stale, i.e. no value was sent since the last time the buffer was read. This connection type is appropriate when you want to automatically get all value updates but want to read them only when you choose. 

Example Use Case: check for new data once every second and read and chart all available values.

Reader

The Reader connection is created by calling the CNVCreateReader function. This connection can be used to read the next value of the variable by calling the CNVRead function. See Figure 3. 

Figure 3: Network Variable Reader: This connection reads the next value of the network variable.

If the variable value has changed since the last read operation the function returns the new value. If not, the function waits for the specified time. If while waiting, the variable value changes, then the new value is returned, and if not, no value is returned. This read operation involves requesting the server hosting the variable to send the next value, and then waiting for the value to be sent over the network. This makes the Reader connection expensive and inappropriate if you want to continuously read the variable value. This connection is appropriate if you only want to sporadically read from the variable, and do not care about all values of the variable. 

Example Use Case: Read the next value when user clicks a button and update user interface.

Asynchronous Reader

The Asynchronous Reader connection is created by calling the CNVCreateAsyncReader function. This connection is similar to the Reader connection and can be used to read the next value of the variable by calling the CNVReadAsync function. See Figure 4. 

Figure 4: Network Variable Asynchronous Reader: This connection reads the next value of the network variable without waiting for a value to be returned to the data callback.

The CNVReadAsync function returns immediately and the user’s callback function is later called with the new data in the library thread. If the variable value has not changed since the last read operation, then the callback function is called only if and when the variable value changes. This connection also requires two network operations to read data and is therefore not appropriate for continuously reading from a variable. This connection is appropriate to sporadically read the next value of the variable without waiting. 

Example Use Case: When user clicks a button read the next value without blocking the user interface.

Writer

The Writer connection is created by calling the CNVCreateWriter function. This connection can be used to write a new value to the variable by calling the CNVWrite function. See Figure 5. 

Figure 5: Network Variable Writer: This connection writes a new value to the network variable.

The write operation waits for the server hosting the variable to receive and acknowledge the new value – this consists of two network operations, one to send the value, and one to get the acknowledgement. You can pass CNVDoNotWait to the CNVWrite function to return without waiting for acknowledgement from the server. This connection is appropriate if you want to write values to the variable and wait for the data to be delivered. 

Example Use Case: When user enters new data, send it to the variable and block the user interface until it gets delivered.

Buffered Writer

The Buffered Writer connection is created by calling the CNVCreateBufferedWriter function. This connection can be used to continuously write values to the variable. See Figure 6. 

Figure 6: Network Variable Buffered Writer: This connection continuously writes values to the network variable.

The CNVPutDataInBuffer function places the value in a local buffer and returns immediately. The library automatically writes the buffered value to the network variable without blocking the user program. The size of the buffer is specified in the CNVCreateBufferedWriter function and can be changed by calling the CNVSetConnectionAttribute function. If the buffer is full, the CNVPutDataInBuffer function waits until the interval specified by the user elapses. If the data could not be places in the buffer within the specified time, then the function fails and returns a timeout error. This connection is appropriate if you want to write values continuously and automatically to the variable. 

Example Use Case: On every timer tick schedule a value to be written to the variable.

Comparison of Read and Write Connections

See Table 1 for a comparison of the various read connections. In most cases, you should use the Subscriber or Buffered Subscriber for best throughput and low latency. For deterministic on-demand reading you can use the Reader model. In specific use-cases, you may want to use the Asynchronous Reader. The Reader and Asynchronous Reader have lower throughput and more latency. 

 

	Subscriber	Buffered Subscriber	Reader	Asynchronous Reader
Read initiation	server-push	server-push	client-pull	client-pull
Data delivery	asynchronous	asynchronous	synchronous	asynchronous
Delivery target	callback function	client buffer	function parameter	callback function
Blocking	no	no	yes	no
Network ops per read	1	1	2	2
Memory overhead	low	depends on buffer size	low	low
Streaming	yes	yes	no	no
Deterministic data retrieval	no	no	yes	no
Data loss probability	lower	lower	higher	higher
Threading complexity	yes	no	no	yes
Caveats	Callback is called on library thread. Return from callback as soon as possible.	Configure large enough buffer and read from buffer frequently. Handle buffer overflow, stale data, and empty buffer conditions.	Handle case where value has not changed and no data is returned.	‘N’ read calls result in ‘N’ callback invocations until the value has changed ‘N’ times. Cannot cancel outstanding reads. Callback is called on library thread. Return from callback quickly.

Table 1: Comparison of Read Connections.

 

See Table 2 for a comparison of the various write connections. In most cases, you should use the Buffered Writer for higher throughput and lower latency. The Writer is useful in cases where you need explicit acknowledgement of data delivery.

	Writer	Buffered Writer
Data delivery	synchronous	asynchronous
Acknowledgement	yes	no
Delivery target	network variable	client buffer
Blocking	yes	only if buffer is full
Memory overhead	low	depends on buffer size
Network ops per write	2	1
Streaming	no	yes
Deterministic data delivery	yes	no
Data loss probability	higher	lower
Caveats	Handle timeout error	Handle buffer-full condition

Table 2: Comparison of Write Connections.

 

Additional Resources

Sign up for the LabWindows/CVI Developer Newsletter to regularly receive technical LabWindows/CVI white papers.
Performance Considerations When Using the LabVIEW Shared Variable [Whitepaper]
Deterministic Communication over Ethernet [Whitepaper]
LabWindows/CVI Resource Page

 

Reader Comments | Submit a comment »