Stream Receive

Receives data over a stream.

Library

Description

The Stream Receive block receives data over a stream. The operation of this block 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 Stream Connect or Stream Accept block which created the stream. The Stream Receive block cannot be used with streams created using the Stream Listen block.

This block receives a vector of values over a client stream, where the size and data type of the signal is determined by the Output data type, Output type name and Dimensions parameters of the block. If the stream has been configured to swap bytes then this block will swap the order of the bytes within each element that it receives before writing them to its data output. Multi-dimensional and variable-size signals, as well as bus signals are supported. See Using Bus Objects with QUARC for more information on bus signals, and refer to Variable-Size Signals for more details on variable-size signals.

If the stream is blocking, then this block waits until all the data is read.

If the stream is non-blocking, then this block does not wait. If fewer bytes are available than the size of the output signal then it returns -QERR_WOULD_BLOCK. In this case, the Stream Poll block may be used to determine when data becomes available. Otherwise the Stream Receive block writes 1 to its err output.

If the connection has been closed gracefully then it returns 0 at its err output only if there are fewer bytes left to receive than the size of the output data vector. Otherwise it returns 1. Once there are fewer bytes left in the stream buffer than the size of the output signal then it will return 0 at its err output to indicate the connection has been closed. If an error occurs, then it returns a negative error code.

This block does not support two threads calling Stream Receive at the same time. However, Stream Receive may be called by another thread at the same time as Stream Send or Stream Flush.

Helpful Hints

Simpler Blocks

The Stream Read block has similar functionality to Stream Receive, but is easier to use. Although it is an Intermediate stream block, it may be used with the Advanced blocks also.

Variable-size signals

When using the Stream Receive block with variable-size signals in subsystems, make sure any

Input Ports

stm

A reference to the stream created by the Stream Connect or Stream Accept block. If the stream is closed or is otherwise invalid then the negative error code -QERR_INVALID_STREAM is returned by the err output.

Output Ports

stm

A reference to the stream. This output is merely a copy of the stm input. Providing this output makes it much easier to establish the execution order of Stream blocks in the diagram because Simulink generally executes daisy-chained blocks in sequence.

data

The data read from the stream buffer. The output signal is treated as an atomic unit. It will never read part of the data from the stream buffer. These semantics make it much easier to deal with streams in Simulink where it is difficult to deal with "parts" of a signal. Note that the buffer size for the stream must be at least as large as the output data or -QERR_STREAM_BUFFER_TOO_SMALL is returned by the err output. Multi-dimensional and variable-size outputs, as well as bus signals are supported. See Using Bus Objects with QUARC for more information on bus signals.

err

An int32 value indicating whether the data was read from the stream buffer successfully. For blocking streams, this value will be 1, unless an error occurs or the connection is closed. If an error occurs then this value is a negative error code. If the connection is closed and not enough data is left in the stream buffer for the output signal then 0 is returned. If the connection is closed but there is enough data in the stream buffer then this block returns 1. Zero is only returned once the stream buffer is exhausted. If the stream is non-blocking and the entire output signal could not be read from the stream buffer then -QERR_WOULD_BLOCK is output. 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. To check for errors in general use the Compare to Zero block to check whether err output is less than zero.

Data Type Support

The Stream Receive block supports signals of any of the built-in Simulink data types at its data output. Multi-dimensional and variable-size signals are supported. Fixed point is not currently supported. See Variable-Size Signals for more information on variable-size signals.

The Stream Receive block also accepts bus signals at its data output. Buses are useful for receiving a mix of different data types in a single receive operation. Bus signals are created using the

Parameters and Dialog Box

Output data type

The data type of the data output. This parameter determines the data type of the elements that are read from the stream. If this parameter is set to Inherited via back propagation then the data type of the output is determined by the block connected to the data output.

If this field is set to Specify via dialog then the Output type name parameter is used to define the data type of the output. Refer to the Output type name parameter for details.

Output type name

This parameter should be the name of a variable in the MATLAB workspace that defines the data type of the output. This variable may be a Simulink.AliasType, Simulink.NumericType, Simulink.StructType or Simulink.Bus object. Simulink.Bus objects may be created using the Simulink Bus Editor, available from the Tools menu of the Simulink diagram.

Dimensions

The dimensions of the output data. This parameter determines how many elements are read from the stream and the dimensions of the data at the data output of the block. It may be a vector with each element being at least 1. For example, to specify a 3-vector, specify 3 as the Dimensions parameter. To output a 2x3 matrix, enter [2, 3].

This field should be 1 when using a bus output.

For variable-sized signals, this parameter specifies the maximum dimensions of the output signal. The dimensions should match the maximum dimensions of the signal on the peer side.

Dimension mode

This option is used to select whether the received signals are fixed-size or variable-sized. If this option is set to Fixed-size output then the received signal is expected to be fixed-size, of the dimensions given by the Dimensions parameter.

If this option is set to Variable-size output then the received signal is expected to be variable-size, with maximum dimension given by the Dimensions parameter. Note that in this case, the Dimensions parameter must be a scalar so the output is a vector.

Finally, if this option is set to Receive dimensions, then the current dimensions of the output signal are read from the stream prior to the data itself. The output signal is then sized according to the received dimensions. The block automatically determines the type of integer required for each dimension based on the maximum dimensions of the output signal specified in the Dimensions parameter. For example, if the maximum size of a dimension is less than 256 then a single 8-bit integer is received for that dimension. If the maximum size is less than 65536 then a 16-bit

integer is used. Dimensions larger than 32-bits are not supported. Refer to Variable-Size Signals for more information on variable-size signals.

Targets

See Also

• Stream Listen block
• Stream Connect block
• Stream Read block
• Stream Scan block
• Stream Send block
• Advanced Communications
• Using Bus Objects with QUARC
• MATLAB Stream Functions
• Communications Using the C Language

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

Link to this page.