Stream Receive
Receives data over a stream.
Library
QUARC Targets/Communications/Advanced
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
Action Port,
Enable or
Trigger ports are
configured to propagate the sizes of variable-size signals during execution. Refer to
Variable-Size Signals for more information
on variable-size signals.
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 Bus Creator block supplied with Simulink. A Simulink.Bus object must be created that defines the data types of the signals within the bus. This object may be created using the Bus Editor and then saved to a MAT file. To ensure that the bus object is always defined, load this MAT file within the InitFcn callback of the Simulink model. See Using Bus Objects with QUARC for more information on bus signals.
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 menu of the
Simulink diagram.
|
Set the Dimensions field to |
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.
| The Variable-size output mode is not recommended except for specialized use cases since data can get out of synchronization depending on the respective timing of the client and server, as well as the communication channel. |
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
|
Target Name |
Compatible* |
Model Referencing |
Comments |
|---|---|---|---|
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
||
|
Yes |
Yes |
Last fully supported in QUARC 2018. |
|
|
Rapid Simulation (RSIM) Target |
Yes |
Yes |
|
|
S-Function Target |
No |
N/A |
Old technology. Use model referencing instead. |
|
Normal simulation |
Yes |
Yes |
If the Stream Connect block which created the stream is not active during normal simulation, then the Stream Receive block does nothing. Otherwise it receives the data from the stream. |
See Also
Copyright ©2024 Quanser Inc. This page was generated 2024-04-16. Submit feedback to Quanser about this page.
Link to this page.
