Stream Write

Sends data over a stream. This block is intended for use in the main diagram.

Library

QUARC Targets/Communications/Intermediate

Description

The Stream Write block writes data to the stream buffer. 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. If a Stream Call or Stream Answer block is used to create the stream, then the stream will be non-blocking. If a Stream Connect or Stream Accept block is used to create the stream then the blocking mode of the stream is determined by the Stream Connect or Stream Listen block.

This block 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 block 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 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 Stream Call or Stream Answer block that created the stream.

If an error occurs, then it returns a negative error code at its err output. If the connection is closed it is considered an error condition. The Compare to Error block may be used to check for specific error codes. If the stream is not valid because it is not yet connected, the err output will be zero since this condition is expected and the validity of the stream may be checked using the con output of the Stream Call or Stream Answer blocks.

This block does not support two threads calling Stream Write at the same time. However, Stream Write may be called by another thread at the same time as Stream Read.

Helpful Hints

Other uses of this block

Although it is intended for use in the main diagram with the other Intermediate stream blocks, the Stream Write block may be used with the Advanced stream blocks, even in an asynchronous thread.

Datagram size and UDP

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 block 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 QERR_DATAGRAM_TOO_LARGE error is returned at the peer when trying to receive the data.

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). For the Simulink blocks or stream API functions, that means using a stream buffer that is at least 1492 bytes in length at the peer. For the lower-level communications API, specify a buffer of at least 1492 bytes in the call to qcomm_receive.

Variable-size signals

When using the Stream Write 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. See Variable-Size Signals for more information on variable-size signals.

Input Ports

stm

A reference to the stream created by the Stream Call or Stream Answer block. If these blocks have not established a connection the err output of the Stream Write block will be zero.

data

The data 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. 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 input signal or -QERR_STREAM_BUFFER_TOO_SMALL is returned by the err output. Multi-dimensional and variable-size signals as well as bus inputs 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.

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.

sent

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.

peer

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.

err

An int32 value indicating whether any errors occurred. It is zero if no errors occurred and a negative error code otherwise. 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, simply test whether the output is non-zero. Note that the QERR_NO_DESIGNATED_PEER error is not reported at this output. It is signalled at the peer output instead since it is not regarded as a fatal error requiring closure of the stream. The QERR_WOULD_BLOCK error is also not reported at this output because it simply indicates that the data could not be sent without blocking. The sent output may be used to determine whether the data was actually written to the stream buffer.

Data Type Support

The Stream Write block accepts signals of any of the built-in Simulink data types at its data input, including multi-dimensional signals. Fixed point is not currently supported.

Variable-size signals are accepted at its data input. In this case, it uses the current dimensions of the signal to determine how many elements to write. Variable-size signals may be multi-dimensional, but cannot be bus signals. See Variable-Size Signals for more information on variable-size signals.

The Stream Write block also accepts bus signals at its data input. Buses are useful for sending a mix of different data types in a single write 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

Optimize for

Determines whether the block is optimized for maximizing throughput or minimizing latency. If this option is set to maximize throughput, then the block 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 block 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.

Send dimensions

This option is used with variable-sized signals. Checking this option causes the current dimensions of the input signal to be sent prior to the data itself so that the peer knows the dimensions of the signal. The block automatically determines the appropriate integer size required for each dimension based on the maximum dimensions of the input signal. For example, if the maximum size of a dimension is less than 256 then a single 8-bit integer is used to transmit 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 Answer block
• Stream Call block
• Stream Formatted Write block
• Stream Read block
• Intermediate Communications
• Using Bus Objects with QUARC
• 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.