Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame^] | 1 | \section{\module{select} --- |
| 2 | Wait for I/O completion on multiple streams.} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | \declaremodule{builtin}{select} |
| 4 | |
| 5 | \modulesynopsis{Wait for I/O completion on multiple streams.} |
| 6 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 7 | |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 8 | This module provides access to the function \cfunction{select()} |
| 9 | available in most \UNIX{} versions. It defines the following: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 10 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 11 | \begin{excdesc}{error} |
| 12 | The exception raised when an error occurs. The accompanying value is |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 13 | a pair containing the numeric error code from \cdata{errno} and the |
| 14 | corresponding string, as would be printed by the \C{} function |
| 15 | \cfunction{perror()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 16 | \end{excdesc} |
| 17 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 18 | \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}} |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 19 | This is a straightforward interface to the \UNIX{} \cfunction{select()} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 20 | system call. The first three arguments are lists of `waitable |
| 21 | objects': either integers representing \UNIX{} file descriptors or |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 22 | objects with a parameterless method named \method{fileno()} returning |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 23 | such an integer. The three lists of waitable objects are for input, |
| 24 | output and `exceptional conditions', respectively. Empty lists are |
Guido van Rossum | 02ee80d | 1995-04-04 12:29:37 +0000 | [diff] [blame] | 25 | allowed. The optional \var{timeout} argument specifies a time-out as a |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 26 | floating point number in seconds. When the \var{timeout} argument |
| 27 | is omitted the function blocks until at least one file descriptor is |
| 28 | ready. A time-out value of zero specifies a poll and never blocks. |
| 29 | |
| 30 | The return value is a triple of lists of objects that are ready: |
| 31 | subsets of the first three arguments. When the time-out is reached |
| 32 | without a file descriptor becoming ready, three empty lists are |
| 33 | returned. |
| 34 | |
| 35 | Amongst the acceptable object types in the lists are Python file |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 36 | objects (e.g. \code{sys.stdin}, or objects returned by |
| 37 | \function{open()} or \function{os.popen()}), socket objects |
| 38 | returned by \function{socket.socket()},% |
| 39 | \withsubitem{(in module socket)}{\ttindex{socket()}} |
| 40 | \withsubitem{(in module posix)}{\ttindex{popen()}} |
| 41 | \withsubitem{(in module os)}{\ttindex{popen()}} |
| 42 | and the module \module{stdwin}\refbimodindex{stdwin} which happens to |
| 43 | define a function \function{fileno()}% |
| 44 | \withsubitem{(in module stdwin)}{\ttindex{fileno()}} |
| 45 | for just this purpose. You may |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 46 | also define a \dfn{wrapper} class yourself, as long as it has an |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 47 | appropriate \method{fileno()} method (that really returns a \UNIX{} |
| 48 | file descriptor, not just a random integer). |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 49 | \end{funcdesc} |