stream_send_array :: QUARC MATLAB Functions

navigation bar

stream_send_array

Sends an arbitrary data type as an atomic unit over a stream.

Syntax

[is_sent, would_block] = stream_send_array(stream, values)

Description

This function writes data to the stream buffer. It attempts to store the values array in the stream buffer according to its data type. It differs from the stream_send function in that it treats the entire array as an atomic unit. It either writes all of the array or none of it. If there is enough room available in the stream buffer then it stores the data in the buffer and returns immediately. The data is not written to the actual communication channel until the stream is flushed using stream_flush or there is no more room available in the stream buffer. If an error occurs, then it issues an error message. If the connection is closed it is considered an error condition.

If stream_listen or stream_connect was called with the non-blocking flag set to false (0), then this function may block attempting to flush the stream buffer. All the data will be consumed and true (1) is returned. Some of the data may remain in the stream buffer and not be sent until the next time stream_flush is called or there is no more room available in the stream buffer. If an error occurs then an error is issued and the stream should be closed.

If stream_listen or stream_connect was called with the non-blocking flag set to true (1), then this function does not block. It returns true (1) if the array is sent successfully. If no items could be sent without blocking, then is_sent is 0 and would_block is set to true (1). If an error occurs then an error is issued and the stream should be closed.

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

Parameters

stream

A stream handle returned by stream_connect or stream_accept.

values

The values to send. The values may be numeric, logical, characters, cell arrays or structures.

Outputs

is_sent

Set to true (1) if the array is written to the stream buffer and zero otherwise. For blocking streams, a value of 0 is returned only if the values array is empty.

would_block

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

Examples

        s.x = 3.14159;
        s.y = 2.71828;
        s.z = int16(172);
        is_sent = stream_send_array(stream, s);    % Send structure as two doubles followed by one 16-bit integer