CL Stream Accept

Owning Palette: Communications/Advanced

Requirements: Quanser Rapid Control Prototyping Toolkit, LabVIEW 2020 or newer, Control Design and Simulation Module

Description

The CL Stream Accept VI accepts a connection from a remote host. A connection is accepted each time the VI executes. 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. The blocking mode of the stream is determined by the CL Stream Listen VI which created the stream. The CL Stream Accept VI cannot be used with streams established using the CL Stream Connect 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.

stream in is a reference to the listening stream created by the CL Stream Listen VI. If the stream is closed or is otherwise invalid then an error will be reported to the Control and Simulation Loop.

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.

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.

status is TRUE if an error occurred. If status is TRUE, the VI does not perform any operations.

code is the error code number identifying an error. A value of 0 means no error, a negative value means a fatal error, and a positive value is a warning. Refer to the Quanser Error Codes for a code description.

source identifies where an error occurred. The source string is usually the name of the VI that produced the error.

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.

send buffer size in bytes is the size of the buffer used by the stream for sending data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase transmission performance. The buffer size must be at least as large as the maximum vector that will be sent. For example, if a double 3-vector is transmitted using the CL Stream Send VI then the stream buffer size must be at least 24 bytes in length since a double is 8 bytes and a 3-vector is being sent.

byte ordering is the order in which bytes are transmitted or received. Little endian ordering means that the least significant byte of individual values, such as doubles, is transmitted or received first. Big endian ordering means that the most significant byte of individual values is transmitted or received first. The remote host must use the same byte ordering. This parameter only affects the accepted stream, not the original listening stream.

receive buffer size in bytes is the size of the buffer used by the stream for receiving data. This buffer is independent of any buffering in the underlying communication protocol. Increasing the buffer size may increase reception performance. The buffer size must be at least as large as the maximum vector that will be received. For example, if a double 5-vector is received using the CL Stream Receive VI then the stream buffer size must be at least 40 bytes in length since a double is 8 bytes and a 5-vector is being received.

Outputs

stream out is a reference to the listening stream. This output is merely a copy of the stream in input.

client stream out is a reference to the accepted client connection. This reference is always valid but will not refer to a connected stream if a connection was not accepted. It has a data type of t_stream_ptr. It cannot be plotted and may only be connected to the stream in input of one of the Stream VIs. It may not be connected to a CL Stream Accept VI. Attempting to do so will result in an error being returned by the CL Stream Accept VI.

would block? is true if the operation would have blocked waiting for a client to connect, and false otherwise. This output is only valid when the stream has been configured as non-blocking. For blocking streams, this output is always false.

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.

	status is TRUE if an error occurred. If status is TRUE, the VI does not perform any operations.
	code is the error code number identifying an error. A value of 0 means no error, a negative value means a fatal error, and a positive value is a warning. Refer to the Quanser Error Codes for a code description.
	source identifies where an error occurred. The source string is usually the name of the VI that produced the error.

Details

In blocking mode, this VI does not return until a connection has been accepted from a remote host. The stream returned for this connection will also be blocking. Blocking mode is more suitable for use in an asynchronous thread rather than a periodic task in the VI so that the sampling rate of the VI is not affected. Asynchronous threads may be created using the Asynchronous Thread VI.

In non-blocking mode, this VI returns immediately. If a client connection was pending, then the connection is accepted. The stream returned for this connection will also be non-blocking. If no client connections are pending then the error code -QERR_WOULD is returned. If the accept failed then another negative error code is returned. All Stream VIs using the accepted connection will also be non-blocking. Whenever such a Stream VI would otherwise wait, the error code -QERR_WOULD is returned instead. When combined with a state machine, non-blocking mode is suitable for periodic tasks because it does not interfere with the sampling rate. The Compare to Error VI may be used to check for specific error codes. The CL Stream Poll VI may be used to wait or poll for the connection to be accepted or other events.

If a connection is accepted then the client stream out output refers to the newly connected stream. This stream signal is passed as an input to other Stream VIs to refer to the new stream. In this case, the err output will be zero. This new stream may not be used to accept new client connections; instead, it is used to send and receive data to and from the remote client. The original listening stream continues to listen for new connections.

The accepted stream must be closed using the CL Stream Close VI when it is no longer in use. A stream that is not closed will remain open until the VI terminates. If the CL Stream Accept VI is invoked more than once then it will close the previously accepted connection, if any, before accepting a new connection. To accept multiple connections at the same time on the same listening stream, use more than one CL Stream Accept VI. Typically, each CL Stream Accept VI is placed in a separate asynchronous thread.

The stream in output refers to the original listening stream. This stream signal may be passed as an input to other CL Stream Accept VIs.

Streams have an associated buffer that is independent of any buffering in the underlying protocol. The CL Stream Accept VI allows the size of the stream buffer to use for the accepted client connection to be specified. The stream buffer is designed to maximize use of the available bandwidth. For example, the CL Stream Send VI simply buffers data until the stream buffer is full and only then does it flush the stream buffer to the underlying communication channel. Similarly, the CL Stream Receive VI simply returns data from the stream buffer. It only reads from the underlying communication channel when there is not enough data in the stream buffer, at which point it attempts to read enough bytes to fill the entire stream buffer.

Feedthrough Behaviour

All input/output pairs of this function have direct feedthrough behaviour.

Examples

RCP CL Comm Advanced Stream Example

Targets

Target	Supported	Comments
RCP Windows (64-bit) Target	Yes	Fully supported.

navigation bar

	CL Stream Close	The CL Stream Close VI closes the stream connected using CL Stream Connect.
	CL Stream Connect	The CL Stream Connect VI establishes a connection to a remote host. The connection is made each time the VI executes.
	CL Stream Flush	The CL Stream Flush VI writes the data in the stream buffer to the underlying communication channel.
	CL Stream Listen	The CL Stream Listen VI creates a stream that listens for connections from remote hosts.
	CL Stream Poll	The CL Stream Poll VI polls for events associated with the connected stream.