Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{select} --- |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 2 | Waiting for I/O completion} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | bbac432 | 1999-02-20 00:14:17 +0000 | [diff] [blame] | 4 | \declaremodule{builtin}{select} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 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 | |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 8 | This module provides access to the \cfunction{select()} |
| 9 | and \cfunction{poll()} functions |
Guido van Rossum | 9814a94 | 1998-09-28 14:28:38 +0000 | [diff] [blame] | 10 | available in most operating systems. Note that on Windows, it only |
| 11 | works for sockets; on other operating systems, it also works for other |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 12 | file types (in particular, on \UNIX, it works on pipes). It cannot |
Fred Drake | 38e5d27 | 2000-04-03 20:13:55 +0000 | [diff] [blame] | 13 | be used on regular files to determine whether a file has grown since |
Guido van Rossum | 9814a94 | 1998-09-28 14:28:38 +0000 | [diff] [blame] | 14 | it was last read. |
| 15 | |
| 16 | The module defines the following: |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 17 | |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 18 | \begin{excdesc}{error} |
| 19 | The exception raised when an error occurs. The accompanying value is |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 20 | a pair containing the numeric error code from \cdata{errno} and the |
| 21 | corresponding string, as would be printed by the \C{} function |
| 22 | \cfunction{perror()}. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 23 | \end{excdesc} |
| 24 | |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 25 | \begin{funcdesc}{poll}{} |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 26 | (Not supported by all operating systems.) Returns a polling object, |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 27 | which supports registering and unregistering file descriptors, and |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 28 | then polling them for I/O events; |
| 29 | see section~\ref{poll-objects} below for the methods supported by |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 30 | polling objects. |
| 31 | \end{funcdesc} |
| 32 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 33 | \begin{funcdesc}{select}{iwtd, owtd, ewtd\optional{, timeout}} |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 34 | This is a straightforward interface to the \UNIX{} \cfunction{select()} |
Brett Cannon | 62dba4c | 2003-09-10 19:37:42 +0000 | [diff] [blame] | 35 | system call. The first three arguments are sequences of `waitable |
Fred Drake | 5255c79 | 2000-12-11 15:50:07 +0000 | [diff] [blame] | 36 | objects': either integers representing file descriptors or |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 37 | objects with a parameterless method named \method{fileno()} returning |
Brett Cannon | 62dba4c | 2003-09-10 19:37:42 +0000 | [diff] [blame] | 38 | such an integer. The three sequences of waitable objects are for input, |
| 39 | output and `exceptional conditions', respectively. Empty sequences are |
| 40 | allowed, but acceptance of three empty sequences is platform-dependent. |
Fred Drake | 5255c79 | 2000-12-11 15:50:07 +0000 | [diff] [blame] | 41 | (It is known to work on \UNIX{} but not on Windows.) The optional |
| 42 | \var{timeout} argument specifies a time-out as a floating point number |
| 43 | in seconds. When the \var{timeout} argument is omitted the function |
| 44 | blocks until at least one file descriptor is ready. A time-out value |
| 45 | of zero specifies a poll and never blocks. |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 46 | |
| 47 | The return value is a triple of lists of objects that are ready: |
| 48 | subsets of the first three arguments. When the time-out is reached |
| 49 | without a file descriptor becoming ready, three empty lists are |
| 50 | returned. |
| 51 | |
Brett Cannon | 62dba4c | 2003-09-10 19:37:42 +0000 | [diff] [blame] | 52 | Among the acceptable object types in the sequences are Python file |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 53 | objects (e.g. \code{sys.stdin}, or objects returned by |
| 54 | \function{open()} or \function{os.popen()}), socket objects |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 55 | returned by \function{socket.socket()}.% |
Fred Drake | b401637 | 1998-04-02 18:44:38 +0000 | [diff] [blame] | 56 | \withsubitem{(in module socket)}{\ttindex{socket()}} |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 57 | \withsubitem{(in module os)}{\ttindex{popen()}} |
Fred Drake | 5255c79 | 2000-12-11 15:50:07 +0000 | [diff] [blame] | 58 | You may also define a \dfn{wrapper} class yourself, as long as it has |
| 59 | an appropriate \method{fileno()} method (that really returns a file |
| 60 | descriptor, not just a random integer). |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 61 | \note{File objects on Windows are not acceptable, but sockets |
| 62 | are.\index{WinSock} On Windows, the underlying \cfunction{select()} |
| 63 | function is provided by the WinSock library, and does not handle file |
Raymond Hettinger | 6880431 | 2005-01-01 00:28:46 +0000 | [diff] [blame] | 64 | descriptors that don't originate from WinSock.} |
Guido van Rossum | 5fdeeea | 1994-01-02 01:22:07 +0000 | [diff] [blame] | 65 | \end{funcdesc} |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 66 | |
| 67 | \subsection{Polling Objects |
| 68 | \label{poll-objects}} |
| 69 | |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 70 | The \cfunction{poll()} system call, supported on most \UNIX{} systems, |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 71 | provides better scalability for network servers that service many, |
| 72 | many clients at the same time. |
| 73 | \cfunction{poll()} scales better because the system call only |
| 74 | requires listing the file descriptors of interest, while \cfunction{select()} |
| 75 | builds a bitmap, turns on bits for the fds of interest, and then |
| 76 | afterward the whole bitmap has to be linearly scanned again. |
| 77 | \cfunction{select()} is O(highest file descriptor), while |
| 78 | \cfunction{poll()} is O(number of file descriptors). |
| 79 | |
| 80 | \begin{methoddesc}{register}{fd\optional{, eventmask}} |
| 81 | Register a file descriptor with the polling object. Future calls to |
| 82 | the \method{poll()} method will then check whether the file descriptor |
| 83 | has any pending I/O events. \var{fd} can be either an integer, or an |
| 84 | object with a \method{fileno()} method that returns an integer. File |
| 85 | objects implement |
| 86 | \method{fileno()}, so they can also be used as the argument. |
| 87 | |
| 88 | \var{eventmask} is an optional bitmask describing the type of events you |
| 89 | want to check for, and can be a combination of the constants |
| 90 | \constant{POLLIN}, \constant{POLLPRI}, and \constant{POLLOUT}, |
| 91 | described in the table below. If not specified, the default value |
| 92 | used will check for all 3 types of events. |
| 93 | |
Fred Drake | 9bbc933 | 2001-07-11 18:48:39 +0000 | [diff] [blame] | 94 | \begin{tableii}{l|l}{constant}{Constant}{Meaning} |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 95 | \lineii{POLLIN}{There is data to read} |
| 96 | \lineii{POLLPRI}{There is urgent data to read} |
| 97 | \lineii{POLLOUT}{Ready for output: writing will not block} |
| 98 | \lineii{POLLERR}{Error condition of some sort} |
| 99 | \lineii{POLLHUP}{Hung up} |
| 100 | \lineii{POLLNVAL}{Invalid request: descriptor not open} |
| 101 | \end{tableii} |
| 102 | |
| 103 | Registering a file descriptor that's already registered is not an |
| 104 | error, and has the same effect as registering the descriptor exactly |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 105 | once. |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 106 | \end{methoddesc} |
| 107 | |
| 108 | \begin{methoddesc}{unregister}{fd} |
| 109 | Remove a file descriptor being tracked by a polling object. Just like |
| 110 | the \method{register()} method, \var{fd} can be an integer or an |
| 111 | object with a \method{fileno()} method that returns an integer. |
| 112 | |
| 113 | Attempting to remove a file descriptor that was never registered |
| 114 | causes a \exception{KeyError} exception to be raised. |
| 115 | \end{methoddesc} |
| 116 | |
| 117 | \begin{methoddesc}{poll}{\optional{timeout}} |
| 118 | Polls the set of registered file descriptors, and returns a |
| 119 | possibly-empty list containing \code{(\var{fd}, \var{event})} 2-tuples |
| 120 | for the descriptors that have events or errors to report. |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 121 | \var{fd} is the file descriptor, and \var{event} is a bitmask |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 122 | with bits set for the reported events for that descriptor |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 123 | --- \constant{POLLIN} for waiting input, |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 124 | \constant{POLLOUT} to indicate that the descriptor can be written to, and |
| 125 | so forth. |
| 126 | An empty list indicates that the call timed out and no file |
| 127 | descriptors had any events to report. |
Fred Drake | 9bbc933 | 2001-07-11 18:48:39 +0000 | [diff] [blame] | 128 | If \var{timeout} is given, it specifies the length of time in |
| 129 | milliseconds which the system will wait for events before returning. |
Fred Drake | c95628e | 2003-04-29 13:56:40 +0000 | [diff] [blame] | 130 | If \var{timeout} is omitted, negative, or \constant{None}, the call will |
Fred Drake | 9bbc933 | 2001-07-11 18:48:39 +0000 | [diff] [blame] | 131 | block until there is an event for this poll object. |
Andrew M. Kuchling | 99a3701 | 2000-08-25 01:21:28 +0000 | [diff] [blame] | 132 | \end{methoddesc} |