FILE_POLL_INPUT

Given a list of file logical units (LUNs), the FILE_POLL_INPUT function will block (not return) until it detects that a read operation for a byte of data from at least one of the specified files will succeed. On return, FILE_POLL_INPUT reports True (1) for each file for which a read operation will succeed, or False (0) for those that will not succeed.

This operation is of particular interest when using internet socket files opened with the SOCKET procedure. If a program opens multiple sockets and reads from any one of them, the read operation will block until data becomes available from the server on the other end of the connection. While blocked in an input operation, the program is unable to respond to data that might become available on any of the other sockets. This can be a serious problem, since latencies on internet connections can be large, and response times inconsistent. The solution to this problem is to block in FILE_POLL_INPUT, giving it the file LUNs of all the open socket files. FILE_POLL_INPUT will wait until one or more of the specified files has data available, and then return the blocking status of each file.

If FILE_POLL_INPUT returns False for a given file, your program can safely assume that a read operation on that file will block for an arbitrary amount of time until data becomes available. If it returns True, the current situation is one of the following:

There is at least one byte of data immediately available
An input operation on that file will immediately generate an error. For example, a file that is at EOF (end of file) will be reported as True

In other words, a True value from FILE_POLL_INPUT ensures that an input operation will not block, not that it will necessarily succeed.

In the case where a True value from FILE_POLL_INPUT means that there is data available, the guarantee only applies to a single byte of data. If your program is expecting to read more than a single byte, the possibility exists that your program will still block while waiting for data beyond the first byte. In cases where this is a critical concern, you may need to use repeated calls to FILE_POLL_INPUT, reading your data one byte at a time. In the vast majority of cases this is unnecessary; the presence of the first byte of data is a strong indication that the rest of the data is either present or will be present in the very near future. For example, if you are reading a 4-byte integer, the presence of the 1st byte is a fairly safe indication that the following 3 bytes are also available.

FILE_POLL_INPUT will return immediately if used with any of the following types of files:

A regular disk file (even if it physically resides on network based storage)
The standard input LUN, if IDL is running with the workbench graphical user interface

Since these file types always return True, there is no reason to ever pass one to FILE_POLL_INPUT. FILE_POLL_INPUT is therefore of primary interest when used with sockets. Under UNIX operating systems, it can also be used with ttys, pipes, and other device special files.

Syntax

Result = FILE_POLL_INPUT(Units [, COUNT=variable] [, TIMEOUT=value] )

Return Value

The result is an array of byte values with the same structure as Units. Each element of the returned array is set to True (1) or False (0), reflecting whether an input operation on the corresponding LUN in Units will succeed or not.

Arguments

Units

A scalar or array of IDL logical file units (LUNs) to be tested. All specified files must be open for input.

Keywords

COUNT

Set this keyword equal to a named variable that will contain the number of True results. If none of the specified files returns True, the variable will contain zero (0).

TIMEOUT

By default, FILE_POLL_INPUT does not return until at least one of the specified files will yield a True value. To change this behavior, set the TIMEOUT keyword equal to a double-precision floating-point value specifying the number of seconds to wait (at most) before the function will return. If TIMEOUT is specified, its value is interpreted as follows:

< 0	Do not return until at least one file yields True (the default behavior).
0	Test the files and return immediately.
> 0	Wait until at least one file yields True or until the specified timeout period expires. In this form, the TIMEOUT keyword places a worst-case bound on the amount of time that will elapse before FILE_POLL_INPUT returns.

Version History

6.2	Introduced