diff -r ffa851df0825 -r 2fb8b9db1c86 symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/select.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/select.rst Fri Jul 31 15:01:17 2009 +0100 @@ -0,0 +1,439 @@ + +:mod:`select` --- Waiting for I/O completion +============================================ + +.. module:: select + :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. +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 +it was last read. + +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`. + + +.. 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 + section :ref:`epoll-objects` below for the methods supported by epolling + objects. + + .. versionadded:: 2.6 + + +.. function:: poll() + + (Not supported by all operating systems.) Returns a polling object, which + supports registering and unregistering file descriptors, and then polling them + for I/O events; see section :ref:`poll-objects` below for the methods supported + by polling objects. + + +.. function:: kqueue() + + (Only supported on BSD.) Returns a kernel queue object object; see section + :ref:`kqueue-objects` below for the methods supported by kqueue objects. + + .. versionadded:: 2.6 + + +.. function:: kevent(ident, filter=KQ_FILTER_READ, flags=KQ_ADD, fflags=0, data=0, udata=0) + + (Only supported on BSD.) Returns a kernel event object object; see section + :ref:`kevent-objects` below for the methods supported by kqueue objects. + + .. versionadded:: 2.6 + + +.. function:: select(rlist, wlist, xlist[, timeout]) + + This is a straightforward interface to the Unix :cfunc:`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: + + * *rlist*: wait until ready for reading + * *wlist*: wait until ready for writing + * *xlist*: wait for an "exceptional condition" (see the manual page for what + your system considers such a condition) + + Empty sequences are allowed, but acceptance of three empty sequences is + platform-dependent. (It is known to work on Unix but not on Windows.) The + optional *timeout* argument specifies a time-out as a floating point number + in seconds. When the *timeout* argument is omitted the function blocks until + at least one file descriptor is ready. A time-out value of zero specifies a + poll and never blocks. + + The return value is a triple of lists of objects that are ready: subsets of the + first three arguments. When the time-out is reached without a file descriptor + becoming ready, three empty lists are returned. + + .. index:: + single: socket() (in module socket) + single: popen() (in module os) + + Among the acceptable object types in the sequences are Python file objects (e.g. + ``sys.stdin``, or objects returned by :func:`open` or :func:`os.popen`), socket + objects returned by :func:`socket.socket`. You may also define a :dfn:`wrapper` + class yourself, as long as it has an appropriate :meth:`fileno` method (that + really returns a file descriptor, not just a random integer). + + .. note:: + + .. 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 + library, and does not handle file descriptors that don't originate from + WinSock. + + +.. _epoll-objects: + +Edge and Level Trigger Polling (epoll) Objects +---------------------------------------------- + + http://linux.die.net/man/4/epoll + + *eventmask* + + +-----------------------+-----------------------------------------------+ + | Constant | Meaning | + +=======================+===============================================+ + | :const:`EPOLLIN` | Available for read | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLOUT` | Available for write | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLPRI` | Urgent data for read | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLERR` | Error condition happened on the assoc. fd | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLHUP` | Hang up happened on the assoc. fd | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLET` | Set Edge Trigger behavior, the default is | + | | Level Trigger behavior | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | + | | pulled out, the fd is internally disabled | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLRDNORM` | ??? | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLRDBAND` | ??? | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLWRNORM` | ??? | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLWRBAND` | ??? | + +-----------------------+-----------------------------------------------+ + | :const:`EPOLLMSG` | ??? | + +-----------------------+-----------------------------------------------+ + + +.. method:: epoll.close() + + Close the control file descriptor of the epoll object. + + +.. method:: epoll.fileno() + + Return the file descriptor number of the control fd. + + +.. method:: epoll.fromfd(fd) + + Create an epoll object from a given file descriptor. + + +.. method:: epoll.register(fd[, eventmask]) + + Register a fd descriptor with the epoll object. + + +.. method:: epoll.modify(fd, eventmask) + + Modify a register file descriptor. + + +.. method:: epoll.unregister(fd) + + Remove a registered file descriptor from the epoll object. + + +.. method:: epoll.poll([timeout=-1[, maxevents=-1]]) + + Wait for events. timeout in seconds (float) + + +.. _poll-objects: + +Polling Objects +--------------- + +The :cfunc:`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 +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). + + +.. method:: poll.register(fd[, eventmask]) + + Register a file descriptor with the polling object. Future calls to the + :meth:`poll` method will then check whether the file descriptor has any pending + I/O events. *fd* can be either an integer, or an object with a :meth:`fileno` + method that returns an integer. File objects implement :meth:`fileno`, so they + can also be used as the argument. + + *eventmask* is an optional bitmask describing the type of events you want to + check for, and can be a combination of the constants :const:`POLLIN`, + :const:`POLLPRI`, and :const:`POLLOUT`, described in the table below. If not + specified, the default value used will check for all 3 types of events. + + +-------------------+------------------------------------------+ + | Constant | Meaning | + +===================+==========================================+ + | :const:`POLLIN` | There is data to read | + +-------------------+------------------------------------------+ + | :const:`POLLPRI` | There is urgent data to read | + +-------------------+------------------------------------------+ + | :const:`POLLOUT` | Ready for output: writing will not block | + +-------------------+------------------------------------------+ + | :const:`POLLERR` | Error condition of some sort | + +-------------------+------------------------------------------+ + | :const:`POLLHUP` | Hung up | + +-------------------+------------------------------------------+ + | :const:`POLLNVAL` | Invalid request: descriptor not open | + +-------------------+------------------------------------------+ + + Registering a file descriptor that's already registered is not an error, and has + the same effect as registering the descriptor exactly once. + + +.. 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 + that was never registered causes an :exc:`IOError` exception with errno + :const:`ENOENT` to be raised. + + .. versionadded:: 2.6 + + +.. method:: poll.unregister(fd) + + Remove a file descriptor being tracked by a polling object. Just like the + :meth:`register` method, *fd* can be an integer or an object with a + :meth:`fileno` method that returns an integer. + + Attempting to remove a file descriptor that was never registered causes a + :exc:`KeyError` exception to be raised. + + +.. method:: poll.poll([timeout]) + + Polls the set of registered file descriptors, and returns a possibly-empty list + containing ``(fd, event)`` 2-tuples for the descriptors that have events or + errors to report. *fd* is the file descriptor, and *event* is a bitmask with + bits set for the reported events for that descriptor --- :const:`POLLIN` for + waiting input, :const:`POLLOUT` to indicate that the descriptor can be written + to, and so forth. An empty list indicates that the call timed out and no file + descriptors had any events to report. If *timeout* is given, it specifies the + length of time in milliseconds which the system will wait for events before + returning. If *timeout* is omitted, negative, or :const:`None`, the call will + block until there is an event for this poll object. + + +.. _kqueue-objects: + +Kqueue Objects +-------------- + +.. method:: kqueue.close() + + Close the control file descriptor of the kqueue object. + + +.. method:: kqueue.fileno() + + Return the file descriptor number of the control fd. + + +.. method:: kqueue.fromfd(fd) + + Create a kqueue object from a given file descriptor. + + +.. method:: kqueue.control(changelist, max_events[, timeout=None]) -> eventlist + + Low level interface to kevent + + - changelist must be an iterable of kevent object or None + - max_events must be 0 or a positive integer + - timeout in seconds (floats possible) + + +.. _kevent-objects: + +Kevent Objects +-------------- + +http://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 + +.. attribute:: kevent.ident + + Value used to identify the event. The interpretation depends on the filter + but it's usually the file descriptor. In the constructor ident can either + be an int or an object with a fileno() function. kevent stores the integer + internally. + +.. attribute:: kevent.filter + + Name of the kernel filter + + +---------------------------+---------------------------------------------+ + | Constant | Meaning | + +===========================+=============================================+ + | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever | + | | there is data available to read | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_WRITE` | Takes a descriptor and returns whenever | + | | there is data available to read | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_AIO` | AIO requests | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested | + | | events watched in *fflag* occurs | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_PROC` | Watch for events on a process id | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device | + | | [not available on Mac OS X] | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is | + | | delivered to the process | + +---------------------------+---------------------------------------------+ + | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer | + +---------------------------+---------------------------------------------+ + +.. attribute:: kevent.flags + + Filter action + + +---------------------------+---------------------------------------------+ + | Constant | Meaning | + +===========================+=============================================+ + | :const:`KQ_EV_ADD` | Adds or modifies an event | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_DELETE` | Removes an event from the queue | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_ENABLE` | Permitscontrol() to returns the event | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_DISABLE` | Disablesevent | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_ONESHOT` | Removes event after first occurrence | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_SYSFLAGS` | internal event | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_FLAG1` | internal event | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_EOF` | Filter specific EOF condition | + +---------------------------+---------------------------------------------+ + | :const:`KQ_EV_ERROR` | See return values | + +---------------------------+---------------------------------------------+ + + +.. attribute:: kevent.fflags + + Filter specific flags + + + :const:`KQ_FILTER_READ` and :const:`KQ_FILTER_WRITE` filter flags + + +----------------------------+--------------------------------------------+ + | Constant | Meaning | + +============================+============================================+ + | :const:`KQ_NOTE_LOWAT` | low water mark of a socket buffer | + +----------------------------+--------------------------------------------+ + + + :const:`KQ_FILTER_VNODE` filter flags + + +----------------------------+--------------------------------------------+ + | Constant | Meaning | + +============================+============================================+ + | :const:`KQ_NOTE_DELETE` | *unlink()* was called | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_WRITE` | a write occurred | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_EXTEND` | the file was extended | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_ATTRIB` | an attribute was changed | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_LINK` | the link count has changed | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_RENAME` | the file was renamed | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_REVOKE` | access to the file was revoked | + +----------------------------+--------------------------------------------+ + + + :const:`KQ_FILTER_PROC` filter flags + + +----------------------------+--------------------------------------------+ + | Constant | Meaning | + +============================+============================================+ + | :const:`KQ_NOTE_EXIT` | the process has exited | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_FORK` | the process has called *fork()* | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_EXEC` | the process has executed a new process | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_PCTRLMASK` | internal filter flag | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_PDATAMASK` | internal filter flag | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_TRACK` | follow a process across *fork()* | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_CHILD` | returned on the child process for | + | | *NOTE_TRACK* | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_TRACKERR` | unable to attach to a child | + +----------------------------+--------------------------------------------+ + + :const:`KQ_FILTER_NETDEV` filter flags [not available on Mac OS X] + + +----------------------------+--------------------------------------------+ + | Constant | Meaning | + +============================+============================================+ + | :const:`KQ_NOTE_LINKUP` | link is up | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_LINKDOWN` | link is down | + +----------------------------+--------------------------------------------+ + | :const:`KQ_NOTE_LINKINV` | link state is invalid | + +----------------------------+--------------------------------------------+ + + +.. attribute:: kevent.data + + Filter specific data + + +.. attribute:: kevent.udata + + User defined value