Stream Accept

Accepts a connection from a remote host.

Library

QUARC Targets/Communications/Advanced

Description

The Stream Accept block accepts a connection from a remote host. A connection is accepted each time the block executes, not at model start. 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 Listen block which created the stream. The Stream Accept block cannot be used with streams established using the Stream Connect block.

In blocking mode, this block 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 model so that the sampling rate of the model is not affected. Asynchronous threads may be created using the Asynchronous Thread block.

In non-blocking mode, this block returns immediately. If a client connection was pending, then the connection is accepted and the err output will be zero. The stream returned for this connection will also be non-blocking. If no client connections are pending then the error code -QERR_WOULD_BLOCK is returned. If the accept failed then another negative error code is returned. All Stream blocks using the accepted connection will also be non-blocking. Whenever such a Stream 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 the connection to be accepted or other events.

If a connection is accepted then the cstm output refers to the newly connected stream. This stream signal is passed as an input to other Stream blocks 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 Stream Close block when it is no longer in use. A stream that is not closed will remain open until the model terminates. If the Stream Accept block 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 Stream Accept block. Typically, each Stream Accept block is placed in a separate asynchronous thread.

The stm output refers to the original listening stream. This stream signal may be passed as an input to other Stream Accept blocks. This output is provided simply to make it easier to control the order in which blocks execute. Simulink generally executes daisy-chained blocks in sequence.

Streams have an associated buffer that is independent of any buffering in the underlying protocol. The Stream Accept block 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 Stream Send block 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 Stream Receive block 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.

Input Ports

stm

A reference to the listening stream created by the Stream Listen 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 listening 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.

cstm

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 stm input of one of the Stream blocks. It may not be connected to a Stream Accept block. Attempting to do so will result in an error being returned by the Stream Accept block.

err

An int32 error code indicating the results of the operation. If a connection is accepted, then this output will be zero. If the listening stream is non-blocking and no client connections are pending then -QERR_WOULD_BLOCK is output. Otherwise another 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

Send buffer size in bytes

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 Stream Send block 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.

Receive buffer size in bytes

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 Stream Receive block 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.

Byte ordering

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.

Targets

See Also

• Stream Listen block
• Stream Connect 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.