diff options
Diffstat (limited to 'Doc/library/select.rst')
| -rw-r--r-- | Doc/library/select.rst | 50 |
1 files changed, 30 insertions, 20 deletions
diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 70f7370..f1fd126 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -1,4 +1,3 @@ - :mod:`select` --- Waiting for I/O completion ============================================ @@ -6,9 +5,9 @@ :synopsis: Wait for I/O completion on multiple streams. -This module provides access to the :cfunc:`select` and :cfunc:`poll` functions -available in most operating systems, :cfunc:`epoll` available on Linux 2.5+ and -:cfunc:`kqueue` available on most BSD. +This module provides access to the :c:func:`select` and :c:func:`poll` functions +available in most operating systems, :c:func:`epoll` available on Linux 2.5+ and +:c:func:`kqueue` available on most BSD. Note that on Windows, it only works for sockets; on other operating systems, it also works for other file types (in particular, on Unix, it works on pipes). It cannot be used on regular files to determine whether a file has grown since @@ -20,11 +19,11 @@ The module defines the following: .. exception:: error The exception raised when an error occurs. The accompanying value is a pair - containing the numeric error code from :cdata:`errno` and the corresponding - string, as would be printed by the C function :cfunc:`perror`. + containing the numeric error code from :c:data:`errno` and the corresponding + string, as would be printed by the C function :c:func:`perror`. -.. function:: epoll([sizehint=-1]) +.. function:: epoll(sizehint=-1) (Only supported on Linux 2.5.44 and newer.) Returns an edge polling object, which can be used as Edge or Level Triggered interface for I/O events; see @@ -54,7 +53,7 @@ The module defines the following: .. function:: select(rlist, wlist, xlist[, timeout]) - This is a straightforward interface to the Unix :cfunc:`select` system call. + This is a straightforward interface to the Unix :c:func:`select` system call. The first three arguments are sequences of 'waitable objects': either integers representing file descriptors or objects with a parameterless method named :meth:`fileno` returning such an integer: @@ -91,10 +90,21 @@ The module defines the following: .. index:: single: WinSock File objects on Windows are not acceptable, but sockets are. On Windows, - the underlying :cfunc:`select` function is provided by the WinSock + the underlying :c:func:`select` function is provided by the WinSock library, and does not handle file descriptors that don't originate from WinSock. +.. attribute:: PIPE_BUF + + The minimum number of bytes which can be written without blocking to a pipe + when the pipe has been reported as ready for writing by :func:`select`, + :func:`poll` or another interface in this module. This doesn't apply + to other kind of file-like objects such as sockets. + + This value is guaranteed by POSIX to be at least 512. Availability: Unix. + + .. versionadded:: 3.2 + .. _epoll-objects: @@ -124,15 +134,15 @@ Edge and Level Trigger Polling (epoll) Objects | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | | | pulled out, the fd is internally disabled | +-----------------------+-----------------------------------------------+ - | :const:`EPOLLRDNORM` | ??? | + | :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` | +-----------------------+-----------------------------------------------+ - | :const:`EPOLLRDBAND` | ??? | + | :const:`EPOLLRDBAND` | Priority data band can be read. | +-----------------------+-----------------------------------------------+ - | :const:`EPOLLWRNORM` | ??? | + | :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` | +-----------------------+-----------------------------------------------+ - | :const:`EPOLLWRBAND` | ??? | + | :const:`EPOLLWRBAND` | Priority data may be written. | +-----------------------+-----------------------------------------------+ - | :const:`EPOLLMSG` | ??? | + | :const:`EPOLLMSG` | Ignored. | +-----------------------+-----------------------------------------------+ @@ -181,13 +191,13 @@ Edge and Level Trigger Polling (epoll) Objects Polling Objects --------------- -The :cfunc:`poll` system call, supported on most Unix systems, provides better +The :c:func:`poll` system call, supported on most Unix systems, provides better scalability for network servers that service many, many clients at the same -time. :cfunc:`poll` scales better because the system call only requires listing -the file descriptors of interest, while :cfunc:`select` builds a bitmap, turns +time. :c:func:`poll` scales better because the system call only requires listing +the file descriptors of interest, while :c:func:`select` builds a bitmap, turns on bits for the fds of interest, and then afterward the whole bitmap has to be -linearly scanned again. :cfunc:`select` is O(highest file descriptor), while -:cfunc:`poll` is O(number of file descriptors). +linearly scanned again. :c:func:`select` is O(highest file descriptor), while +:c:func:`poll` is O(number of file descriptors). .. method:: poll.register(fd[, eventmask]) @@ -226,7 +236,7 @@ linearly scanned again. :cfunc:`select` is O(highest file descriptor), while .. method:: poll.modify(fd, eventmask) Modifies an already registered fd. This has the same effect as - :meth:`register(fd, eventmask)`. Attempting to modify a file descriptor + ``register(fd, eventmask)``. Attempting to modify a file descriptor that was never registered causes an :exc:`IOError` exception with errno :const:`ENOENT` to be raised. |