stream_receive_array :: QUARC MATLAB Functions

navigation bar

stream_receive_array

Receives an arbitrary data type as an atomic unit from a stream.

Syntax

[values, would_block] = stream_receive_array(stream, template)

Description

This function receives data over a client stream. It attempts to receive the same data type as specified in the template argument from the communication channel. It differs from the stream_receive function in that it treats the entire array as an atomic unit. It either receives all of the array or none of it.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function blocks until all the data is read. If the connection has been closed gracefully then it returns an empty array only once there is no more data to receive. Otherwise it returns the array of values read before the connection closed. Once there is not enough data in the stream buffer to fill the requested array then it will return an empty array to indicate the connection has been closed. Use stream_receive to receive any remaining bytes if required. If an error occurs, then it issues an error message.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. If fewer elements are available than the size of the entire requested array then it sets would_block equal to true. In this case, the stream_poll function may be used with the 'receive' flag to determine when data becomes available.

This operation is not valid on listening streams created using stream_listen.

Parameters

stream

A stream handle returned by stream_connect or stream_accept.

template

The data type read from the stream will match the data type of this argument.

Outputs

values

The value received. For blocking streams, if this array is empty then then the connection has been closed gracefully. For non-blocking streams, the array is empty if not enough data was available in the stream buffer to satisfy the request. In this case, would_block is set to true if the connection is still open and false if the connection has been closed. The array is always empty or the same dimensions as the template argument. Unlike the stream_receive function it never contains between 0 and the number of elements in the template array.

would_block

Whether the function would have blocked. Always false for blocking streams.

Examples

        s.x = 0.0;
        s.y = 0.0;
        s.z = int16(0);
        value = stream_receive_array(stream, s);    % Receive a structure as two doubles followed by one 16-bit integer