stream_poll :: QUARC MATLAB Functions

navigation bar

stream_poll

Polls the stream for different conditions.

Syntax

satisfied = stream_poll(stream, timeout, conditions)
satisfied = stream_poll(stream, conditions)

Description

This function polls the stream to determine whether it is possible to send, receive or accept a connection without blocking. The conditions argument determines the conditions for which to check. If a condition is satisfied, then the corresponding stream function is guaranteed not to block. For example, if the 'receive' condition is satisfied, then calling stream_receive to receive one byte is guaranteed not to block because at least one byte is available in the stream buffer. The sole exception is the 'connect' condition, which indicates that a previously executed non-blocking stream_connect call has completed. There is no need to call stream_connect again.

The timeout argument is a real scalar indicating the maximum time to wait for an event to occur in seconds. If no timeout argument is specified then the function waits indefinitely i.e., the timeout is equivalent to inf. Alternatively, a timeout of inf may be specified for an infinite timeout.

The conditions argument is either a string or a cell array of strings indicating the conditions for which to wait. Each string may be one of the following values:

'receive'	-	not valid on a listening stream. On a client stream, check whether there is any data available to receive. A subsequent call to stream_receive for one byte is guaranteed not to block.
'send'	-	not valid on a listening stream. On a client stream, check whether there is space in the stream buffer to store any data. A subsequent call to stream_send to send one byte is guaranteed not to block.
'flush'	-	not valid on a listening stream. On a client stream, check whether it is possible to flush any more data without blocking. A subsequent call to stream_flush will flush at least one more byte to the underlying stream. However, for blocking streams, the stream_flush may block if there is more than one byte still left in the output stream buffer.
'accept'	-	not valid on a client stream. On a listening stream, check whether there is a pending client connection. A subsequent call to stream_accept will not block.
'connect'	-	not valid on a listening stream. On a client stream, check whether the connection has completed.

The satisfied return value indicates the conditions which occurred. It is a logical vector in which an element is true (1) if the condition occurred before the timeout or false (0) if it did not. The order of the elements in this vector is the same as the order of the conditions specified in the conditions cell array. If the conditions argument is just a string, then the satisfied output is simply a logical scalar value.

If the timeout occurs before any of the conditions are satisifed, then the satisfied ouput will be entire false. The return value is typically used as follows:

            if isany(satisfied) % then at least one condition was satisfied.
            ...
            else                % the timeout occurred and no condition was satisfied.
            ...
            end

The stream_poll function returns before the timeout if at least one of the conditions occurs before the timeout interval expires. It does not wait for the entire timeout interval to satisfy as many conditions as possible.

Parameters

stream

Stream handle returned by stream_connect or stream_accept.

timeout

The timeout interval in seconds e.g. 0.1 to wait 1/10th of a second.

conditions

A string, or a cell array of strings, indicating the conditions for which to wait.

Outputs

satisfied

A logical vector where each element indicates whether the corresponding condition in the conditions argument has been satisfied.

Examples

satisfied = stream_poll(stream, 0.5, 'accept');    % Wait 0.5 seconds for a client to begin connecting.