CL Stream Write
| Owning Palette: | Communications/Intermediate |
| Requirements: | Quanser Rapid Control Prototyping Toolkit, LabVIEW 2020 or newer, Control Design and Simulation Module |
Description
The CL Stream Write VI writes data to the stream buffer. The operation of this VI is affected by the blocking mode of the stream connected to its input. Streams have two modes: blocking (the default) and non-blocking. If a CL Stream Call or CL Stream Answer VI is used to create the stream, then the stream will be non-blocking. If a CL Stream Connect or CL Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the CL Stream Connect or CL Stream Listen VI.
Required Inputs 
All required inputs must be wired. They always appear as terminals on the VI palette. They also appear in bold text in the context help window for the VI.
|
steam in is a reference to the stream created by the Stream Call or Stream Answer VI. If these VIs have not established a connection the err output of the CL Stream Write VI will be zero. |
Recommended Inputs or Dialog Box Options
Recommended inputs need not to be wired. They may be selected to appear as terminals or dialog parameters, but show up as terminals by default.
They appear in simple text in the context help window for the VI.
|
value to stream to write to the stream. The input signal is treated as an atomic unit.
It will never write part of the data to the stream. Note that the buffer size for the stream must be at least as large
as the input signal or |
|
error in describes error conditions occurring before the VI executes. If an error has already occurred, the VI returns the value of the error in cluster in error out.
|
Optional Inputs or Dialog Box Options
Optional inputs need not to be wired. They may appear as terminals or dialog parameters, but show up as dialog parameters by default.
They are indicated but not labelled in the context help window for the VI.
|
optimize for determines whether the VI is optimized for maximizing throughput or minimizing latency. If this option is set to maximize throughput, then the VI only flushes the stream buffer to the underlying communication channel when the stream buffer is full. In this way, as much data as possible can be transferred in each packet for packet-based protocols such as TCP/IP or UDP. If this option is set to minimize latency then it flushes the stream buffer to the underlying communication channel each time the VI executes. Doing so minimizes the time between when the data is generated and when it is sent to the remote host, but it may under-utilize the communications bandwidth since packets may not be full when they are sent. |
Outputs
|
steam out is a reference to the stream. This output is merely a copy of the stm input. |
||||||
|
sent? is a Boolean value indicating whether the input signal was written to the stream buffer successfully. This value will be true (non-zero) if the data was written successfully and zero otherwise. If the data could not be written immediately without blocking then this output will be zero. This output merely indicates that the data was written to the stream buffer. It does not validate that the data was sent to the underlying communication channel or delivered to the remote peer successfully. |
||||||
|
|
no designated peer? is a Boolean value indicating whether an error has occurred due to the peer not yet being designated. For a UDP server, the client is generally unknown until the first receive operation has been completed successfully, because the UDP protocol is a connection-less protocol. Not knowing the peer means no data will be sent. However, it is not regarded as a fatal error because the stream does not need to be closed in this case. It merely indicates that no client has "connected" yet by sending a datagram to the server. The UDP server should continue listening on the port and attempting to receive data. This output can be used to determine why no data has been sent (see the sent? port) when there are no other errors and the operation should not have blocked. |
||||||
|
error out contains error information. If the error in cluster indicated an error, the error out cluster contains the same information. Otherwise, error out describes the error status of this VI.
|
Details
The CL Stream Write VI writes data to the stream buffer. The operation of this VI is affected by the blocking mode of the stream connected to its input. Streams have two modes: blocking (the default) and non-blocking. If a CL Stream Call or CL Stream Answer VI is used to create the stream, then the stream will be non-blocking. If a CL Stream Connect or CL Stream Accept VI is used to create the stream then the blocking mode of the stream is determined by the CL Stream Connect or CL Stream Listen VI.
This VI attempts to store all of the data at its data input in the stream buffer. If the stream has been configured to swap bytes due to endian differences then this VI will swap the order of the bytes within each element in the input signal when storing the data in the stream buffer. If the Optimize for parameter is set to minimize latency then it will also flush the stream each time that it executes. Otherwise, it only flushes the stream buffer to the underlying communication channel when the stream buffer is full. The size of the stream buffer is set by the Send buffer size parameter of the CL Stream Call or CL Stream Answer VI that created the stream.
If an error occurs, it will be reported to Control and Simulation Loop. If the connection is closed it is considered an error condition. If the stream is not valid because it is not yet connected, the VI will not report error since this condition is expected and the validity of the stream may be checked using the state output of the CL Stream Call or CL Stream Answer VIs.
This VI does not support two threads calling CL Stream Write at the same time. However, CL Stream Write may be called by another thread at the same time as CL Stream Read.
| Although it is intended for use in the main diagram with the other Intermediate stream VIs, the CL Stream Write VI may be used with the Advanced stream VIs, even in an asynchronous thread. |
|
For packet or message-based protocols in non-blocking mode, the number of bytes
sent over the communication channel in each packet may be larger than the number
of bytes in the input signal, even if the VI is configured to minimize latency.
If the data cannot be flushed to the underlying communication channel without blocking
then it remains in the stream buffer and will be written to the underlying communication
channel along with the new data on the next sampling instant. This situation is
typically recognized when a |
| The number of bytes in each packet may be as large as the stream buffer size unless the underlying protocol restricts the maximum packet size. For example, the bufsize option of the UDP protocol has a default value of 1492 bytes. Hence, up to 1492/8 = 186 doubles may appear in a single datagram at the peer if the stream buffer is more than 1492 bytes in size. To restrict the size of the datagrams sent, either reduce the stream buffer size or set the bufsize option of the UDP URI. Reducing the stream buffer size may cause new data to be discarded if there is not enough room in the stream buffer, but it limits the number of datagrams sent. Setting the bufsize option of the UDP URI causes the stream API to send multiple datagrams, if necessary, to flush the stream buffer. A typical URI would be "udp://localhost:18000?bufsize=512", which sets the maximum datagram size to 512 bytes (64 doubles). |
| An even better solution is to allow the datagrams to be large and instead receive the full datagram at the peer. For example, if the stream buffer size and maximum datagram size are both 1492 bytes, then attempt to receive 1492 bytes at the peer (or 187 doubles). |
Feedthrough Behaviour
All input/output pairs of this function have direct feedthrough behaviour.
Examples
| RCP CL Comm Advanced Stream Example | ||
| RCP CL Comm Intermediate Stream Example | ||
| RCP CL Comm Intermediate Stream Mixed Type Example |
See Also
| CL Stream Read | ||
| CL Stream Answer | The CL Stream Answer VI listens for and accepts a connection from a remote host using non-blocking I/O. Non-blocking I/O is used so that the I/O does not interfere with the sample rate of the VI. However, as a result, communication protocols that do not support non-blocking I/O are not supported by the Intermediate Stream VIs. | |
| CL Stream Call |
Targets
|
Target |
Supported |
Comments |
|---|---|---|
|
Yes |
Fully supported. |
Copyright © Quanser Inc. This page was generated 2021-09-24. Submit feedback to Quanser about this page.
Link to this page.