diff --git a/Doc/library/select.rst b/Doc/library/select.rst index 6400005871746a..3772255e9642fe 100644 --- a/Doc/library/select.rst +++ b/Doc/library/select.rst @@ -305,41 +305,41 @@ Edge and level trigger polling (epoll) objects +-------------------------+------------------------------------------------+ | Constant | Meaning | +=========================+================================================+ - | :const:`EPOLLIN` | Available for read. | + | .. data:: EPOLLIN | Available for read. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLOUT` | Available for write. | + | .. data:: EPOLLOUT | Available for write. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLPRI` | Urgent data for read. | + | .. data:: EPOLLPRI | Urgent data for read. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLERR` | Error condition happened on the associated fd. | + | .. data:: EPOLLERR | Error condition happened on the associated fd. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLHUP` | Hang up happened on the associated fd. | + | .. data:: EPOLLHUP | Hang up happened on the associated fd. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLET` | Set Edge Trigger behavior, the default is | + | .. data:: EPOLLET | Set Edge Trigger behavior, the default is | | | Level Trigger behavior. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLONESHOT` | Set one-shot behavior. After one event is | + | .. data:: EPOLLONESHOT | Set one-shot behavior. After one event is | | | pulled out, the fd is internally disabled. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLEXCLUSIVE` | Wake only one epoll object when the | + | .. data:: EPOLLEXCLUSIVE| Wake only one epoll object when the | | | associated fd has an event. The default (if | | | this flag is not set) is to wake all epoll | | | objects polling on an fd. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLRDHUP` | Stream socket peer closed connection or shut | + | .. data:: EPOLLRDHUP | Stream socket peer closed connection or shut | | | down writing half of connection. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` | + | .. data:: EPOLLRDNORM | Equivalent to :const:`EPOLLIN` | +-------------------------+------------------------------------------------+ - | :const:`EPOLLRDBAND` | Priority data band can be read. | + | .. data:: EPOLLRDBAND | Priority data band can be read. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT`. | + | .. data:: EPOLLWRNORM | Equivalent to :const:`EPOLLOUT`. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLWRBAND` | Priority data may be written. | + | .. data:: EPOLLWRBAND | Priority data may be written. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLMSG` | Ignored. | + | .. data:: EPOLLMSG | Ignored. | +-------------------------+------------------------------------------------+ - | :const:`EPOLLWAKEUP` | Prevents sleep during event waiting. | + | .. data:: EPOLLWAKEUP | Prevents sleep during event waiting. | +-------------------------+------------------------------------------------+ .. versionadded:: 3.6 @@ -417,6 +417,28 @@ on bits for the fds of interest, and then afterward the whole bitmap has to be linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), while :c:func:`!poll` is *O*\ (*number of file descriptors*). +The event masks that can be used with polling objects are combinations of the +following constants: + + +--------------------+-------------------------------------------+ + | Constant | Meaning | + +====================+===========================================+ + | .. data:: POLLIN | There is data to read. | + +--------------------+-------------------------------------------+ + | .. data:: POLLPRI | There is urgent data to read. | + +--------------------+-------------------------------------------+ + | .. data:: POLLOUT | Ready for output: writing will not block. | + +--------------------+-------------------------------------------+ + | .. data:: POLLERR | Error condition of some sort. | + +--------------------+-------------------------------------------+ + | .. data:: POLLHUP | Hung up. | + +--------------------+-------------------------------------------+ + | .. data:: POLLRDHUP| Stream socket peer closed connection, or | + | | shut down writing half of connection. | + +--------------------+-------------------------------------------+ + | .. data:: POLLNVAL | Invalid request: descriptor not open. | + +--------------------+-------------------------------------------+ + .. method:: poll.register(fd[, eventmask]) @@ -428,28 +450,9 @@ linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), w *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 + :const:`POLLPRI`, and :const:`POLLOUT`, described in the table above. 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:`POLLRDHUP`| Stream socket peer closed connection, or | - | | shut down writing half of connection. | - +-------------------+-------------------------------------------+ - | :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. @@ -459,7 +462,7 @@ linearly scanned again. :c:func:`!select` is *O*\ (*highest file descriptor*), w Modifies an already registered fd. This has the same effect as ``register(fd, eventmask)``. Attempting to modify a file descriptor that was never registered causes an :exc:`OSError` exception with errno - :const:`ENOENT` to be raised. + :data:`~errno.ENOENT` to be raised. .. method:: poll.unregister(fd) @@ -522,9 +525,9 @@ Kqueue objects Create a kqueue object from a given file descriptor. -.. method:: kqueue.control(changelist, max_events[, timeout]) -> eventlist +.. method:: kqueue.control(changelist, max_events[, timeout]) - Low level interface to kevent + Low level interface to kevent, returning a list of events. - changelist must be an iterable of kevent objects or ``None`` - max_events must be 0 or a positive integer @@ -562,26 +565,26 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +---------------------------+---------------------------------------------+ | Constant | Meaning | +===========================+=============================================+ - | :const:`KQ_FILTER_READ` | Takes a descriptor and returns whenever | + | .. data:: 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 | + | .. data:: KQ_FILTER_WRITE | Takes a descriptor and returns whenever | | | there is data available to write. | +---------------------------+---------------------------------------------+ - | :const:`KQ_FILTER_AIO` | AIO requests. | + | .. data:: KQ_FILTER_AIO | AIO requests. | +---------------------------+---------------------------------------------+ - | :const:`KQ_FILTER_VNODE` | Returns when one or more of the requested | + | .. data:: 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. | + | .. data:: KQ_FILTER_PROC | Watch for events on a process ID. | +---------------------------+---------------------------------------------+ - | :const:`KQ_FILTER_NETDEV` | Watch for events on a network device | + | .. data:: KQ_FILTER_NETDEV| Watch for events on a network device | | | (not available on macOS). | +---------------------------+---------------------------------------------+ - | :const:`KQ_FILTER_SIGNAL` | Returns whenever the watched signal is | + | .. data:: KQ_FILTER_SIGNAL| Returns whenever the watched signal is | | | delivered to the process. | +---------------------------+---------------------------------------------+ - | :const:`KQ_FILTER_TIMER` | Establishes an arbitrary timer. | + | .. data:: KQ_FILTER_TIMER | Establishes an arbitrary timer. | +---------------------------+---------------------------------------------+ .. attribute:: kevent.flags @@ -591,25 +594,25 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +---------------------------+----------------------------------------------+ | Constant | Meaning | +===========================+==============================================+ - | :const:`KQ_EV_ADD` | Adds or modifies an event. | + | .. data:: KQ_EV_ADD | Adds or modifies an event. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_DELETE` | Removes an event from the queue. | + | .. data:: KQ_EV_DELETE | Removes an event from the queue. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_ENABLE` | Permits control() to return the event. | + | .. data:: KQ_EV_ENABLE | Permits control() to return the event. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_DISABLE` | Disables event. | + | .. data:: KQ_EV_DISABLE | Disables event. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_ONESHOT` | Removes event after first occurrence. | + | .. data:: KQ_EV_ONESHOT | Removes event after first occurrence. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_CLEAR` | Reset the state after an event is retrieved. | + | .. data:: KQ_EV_CLEAR | Reset the state after an event is retrieved. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_SYSFLAGS` | Internal event. | + | .. data:: KQ_EV_SYSFLAGS | Internal event. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_FLAG1` | Internal event. | + | .. data:: KQ_EV_FLAG1 | Internal event. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_EOF` | Filter-specific EOF condition. | + | .. data:: KQ_EV_EOF | Filter-specific EOF condition. | +---------------------------+----------------------------------------------+ - | :const:`KQ_EV_ERROR` | See return values. | + | .. data:: KQ_EV_ERROR | See return values. | +---------------------------+----------------------------------------------+ @@ -622,7 +625,7 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +----------------------------+--------------------------------------------+ | Constant | Meaning | +============================+============================================+ - | :const:`KQ_NOTE_LOWAT` | Low water mark of a socket buffer. | + | .. data:: KQ_NOTE_LOWAT | Low water mark of a socket buffer. | +----------------------------+--------------------------------------------+ :const:`KQ_FILTER_VNODE` filter flags: @@ -630,19 +633,19 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +----------------------------+--------------------------------------------+ | Constant | Meaning | +============================+============================================+ - | :const:`KQ_NOTE_DELETE` | *unlink()* was called. | + | .. data:: KQ_NOTE_DELETE | *unlink()* was called. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_WRITE` | A write occurred. | + | .. data:: KQ_NOTE_WRITE | A write occurred. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_EXTEND` | The file was extended. | + | .. data:: KQ_NOTE_EXTEND | The file was extended. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_ATTRIB` | An attribute was changed. | + | .. data:: KQ_NOTE_ATTRIB | An attribute was changed. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_LINK` | The link count has changed. | + | .. data:: KQ_NOTE_LINK | The link count has changed. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_RENAME` | The file was renamed. | + | .. data:: KQ_NOTE_RENAME | The file was renamed. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_REVOKE` | Access to the file was revoked. | + | .. data:: KQ_NOTE_REVOKE | Access to the file was revoked. | +----------------------------+--------------------------------------------+ :const:`KQ_FILTER_PROC` filter flags: @@ -650,22 +653,22 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +----------------------------+--------------------------------------------+ | Constant | Meaning | +============================+============================================+ - | :const:`KQ_NOTE_EXIT` | The process has exited. | + | .. data:: KQ_NOTE_EXIT | The process has exited. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_FORK` | The process has called *fork()*. | + | .. data:: KQ_NOTE_FORK | The process has called *fork()*. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_EXEC` | The process has executed a new process. | + | .. data:: KQ_NOTE_EXEC | The process has executed a new process. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_PCTRLMASK` | Internal filter flag. | + | .. data:: KQ_NOTE_PCTRLMASK| Internal filter flag. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_PDATAMASK` | Internal filter flag. | + | .. data:: KQ_NOTE_PDATAMASK| Internal filter flag. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_TRACK` | Follow a process across *fork()*. | + | .. data:: KQ_NOTE_TRACK | Follow a process across *fork()*. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_CHILD` | Returned on the child process for | + | .. data:: KQ_NOTE_CHILD | Returned on the child process for | | | *NOTE_TRACK*. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_TRACKERR` | Unable to attach to a child. | + | .. data:: KQ_NOTE_TRACKERR | Unable to attach to a child. | +----------------------------+--------------------------------------------+ :const:`KQ_FILTER_NETDEV` filter flags (not available on macOS): @@ -673,11 +676,11 @@ https://man.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2 +----------------------------+--------------------------------------------+ | Constant | Meaning | +============================+============================================+ - | :const:`KQ_NOTE_LINKUP` | Link is up. | + | .. data:: KQ_NOTE_LINKUP | Link is up. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_LINKDOWN` | Link is down. | + | .. data:: KQ_NOTE_LINKDOWN | Link is down. | +----------------------------+--------------------------------------------+ - | :const:`KQ_NOTE_LINKINV` | Link state is invalid. | + | .. data:: KQ_NOTE_LINKINV | Link state is invalid. | +----------------------------+--------------------------------------------+ diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore index 2255c745c00383..23b6d56756e34a 100644 --- a/Doc/tools/.nitignore +++ b/Doc/tools/.nitignore @@ -20,7 +20,6 @@ Doc/library/multiprocessing.rst Doc/library/optparse.rst Doc/library/pickletools.rst Doc/library/pyexpat.rst -Doc/library/select.rst Doc/library/socket.rst Doc/library/ssl.rst Doc/library/termios.rst