Stream Listen

Creates a stream that listens for connections from remote hosts.

Library

QUARC Targets/Communications/Advanced

Description

The Stream Listen block creates a stream that listens for connections from remote hosts. The stream is created each time the block executes, not at model start. Streams have two modes: blocking (the default) and non-blocking. This block returns immediately regardless whether the stream is blocking or non-blocking.

However, in non-blocking mode, any Stream Accept block using the stream will also be non-blocking. Furthermore, connections accepted from remote hosts will be non-blocking. Whenever a Stream Accept block would otherwise wait, the error code -QERR_WOULD_BLOCK 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 block may be used to check for specific error codes. The Stream Poll block may be used to wait or poll for a connection to be accepted or other events.

Blocking mode is more suitable for use in an asynchronous thread rather than a periodic task in the model so that the sampling rate of the model is not affected. Asynchronous threads may be created using the Asynchronous Thread block.

If the stream is created successfully then the stm output refers to the connected stream. This stream signal is passed as an input to Stream Accept blocks to refer to the stream. In this case, the err output will be zero.

If the stream could not be created then the err output will be a negative error code. The stm output is never zero, even when the stream cannot be created, because it is a reference to the stream rather than the stream handle itself. Hence, it cannot be used directly to determine whether the stream is valid.

The communication channel used for streams is identified by a Universal Resource Identifier (URI), such as tcpip://localhost:18000 or serial://localhost:1?baud=57600. QUARC uses URI's for all its communications because it provides a uniform, extensible and flexible means of identifying the communication protocol to use and the associated communication parameters. Refer to Universal Resource Identifiers for more information.

When the URI is specified as a dialog parameter and is not evaluated then the URI is configuration-dependent. A separate URI may be entered for each model configuration as well as for normal simulation. Thus, it is possible to employ a different URI for each target, without making a new diagram. The URI that is entered becomes the URI for the currently active configuration when the Simulation mode is set to External. It becomes the URI for normal simulation when the Simulation mode is set to Normal.

The URI may be specified in the dialog parameters or via an input port. Which option is used is determined by the Source of URI parameter. When the URI is specified via an input, the input is typically driven by a Model Argument block, which allows a model argument to be used to assign the URI at runtime.

Helpful Hints

Firewall

If remote clients will be communicating with the server then be sure to configure the server machine's firewall to allow incoming access on the port being used.

Multiple NICs and UDP

When using the UDP protocol, the network interface card (NIC) from which datagrams are received may be specified using the nic option. Refer to the UDP Protocol for details. Unlike other protocols, it is also possible for two Stream Listen blocks to communicate with each other rather than requiring a Stream Listen and Stream Connect block.

Input Ports

uri

A string specifying the URI upon which to listen for client connections. The string must be a null-terminated vector of characters represented as a vector of uint8 quantities. It may be variable-sized. This string is typically provided either directly or indirectly by a Model Argument block or String Constant block.

This input is only available if the Source of URI parameter is set to External input port. Refer to the documentation below on the Source of URI parameter for details.

Output Ports

stm

A reference to the stream. This reference is always valid but will not refer to a listening stream if the stream could not be created. It has a data type of t_stream_ptr. It cannot be plotted and may only be connected to the stm input of one of the Stream blocks. It may not be connected to a Stream Send, Stream Flush or Stream Receive block. Attempting to do so will result in an error being returned by that block.

err

An int32 error code indicating the result of the operation. If the listening stream is created successfully, then this output will be zero. Otherwise a negative error code is returned. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes.

Parameters and Dialog Box

Source of URI

Indicates whether the URI should be determined from the dialog parameters or an input port. If this field is set to Specify via dialog (do not evaluate) then the URI is specified via the URI upon which to listen parameter. In this case, the URI is not evaluated as a MATLAB expression but is interpreted as a literal string. However, format specifiers are recognized. Refer to qc_perform_substitutions for a list of the format specifiers available.

If this field is set to Specify via dialog (evaluate) then the URI is also specified via the URI upon which to listen parameter. However, in this case, the URI is evaluated as a MATLAB expression. This option is convenient for using a variable in the MATLAB workspace for the URI.

If this field is set to External input port then the URI upon which to listen parameter is ignored and an extra input port is provided which determines the URI.

URI upon which to listen (tunable offline)

The URI identifying the communication channel upon which to listen for connections from remote hosts, and the associated communication parameters. For example, tcpip://localhost:18000?backlog=10 listens for connections on TCP/IP port 18000 and allows up to 10 client connections to be queued while awaiting acceptance by a Stream Accept block. This field is only used if the Source of URI parameter is set to Specify via dialog (do not evaluate) or Specify via dialog (evaluate). Refer to Universal Resource Identifiers for more information about URIs and the communications protocols supported by QUARC.

Sample time

The sample time of the block. A sample time of 0 indicates that the block will be treated as a continuous time block. A positive sample time indicates that the block is a discrete time block with the given sample time.

A sample time of -1 indicates that the block inherits its sample time. Since this is a source block, only inherent the sample time when it is placed in a conditionally executed subsystem, like a Triggered Subsystem, Enabled Subsystem, Function Call Subsystem or in a referenced model.

To use the fundamental sampling time of the model, set the sample time to qc_get_step_size, which is a QUARC function that returns the fundamental sampling time of the model.

The default sample time is set to qc_get_step_size.

Non-blocking (tunable offline)

Check this option to make the stream non-blocking. In this case, all blocks using the stream become nonblocking; this block will return immediately but any Stream Accept block using this stream will not wait for a connection to be accepted. Instead, whenever the Stream Accept block would otherwise wait, the error code -QERR_WOULD_BLOCK is returned. See Error Codes for the different error codes and their values. Use the Compare to Error block rather than the error code itself to check for specific error codes.

Active during normal simulation (tunable offline)

Indicates whether this block should execute during normal simulation. If this option is not checked then the block will not create a listening stream during normal simulation. This parameter has no effect on generated code.

Targets

See Also

• Stream Connect block
• Stream Accept block
• Stream Close block
• Advanced Communications
• MATLAB Stream Functions
• Communications Using the C Language

Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.

Link to this page.