Skip to content

bpo-29247: Document return value of epoll.poll() #4798

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

bpo-29247: Document return value of epoll.poll() #4798

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6e05da7
bpo-29247: Document return value of epoll.poll()
berkerpeksag Dec 11, 2017
a6183ee
More fixes
berkerpeksag Dec 11, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 59 additions & 55 deletions Doc/library/select.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -264,48 +264,17 @@ object.
Edge and Level Trigger Polling (epoll) Objects
----------------------------------------------

https://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:`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 a fd. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDHUP` | Stream socket peer closed connection or shut |
| | down writing half of connection. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDBAND` | Priority data band can be read. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLWRBAND` | Priority data may be written. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLMSG` | Ignored. |
+-------------------------+-----------------------------------------------+
.. method:: epoll.poll(timeout=-1, maxevents=-1)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was there a reason for moving epoll.poll? The other sections (devpoll and poll) both have the .poll method defined last in the section. I don't know which is better, but moving this makes it inconsistent.


Wait for events. *timeout* in seconds (float) Return a list of
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can timeout be explained better? It's not really a proper sentence here. Also, maxevents isn't explained. Is it the number of tuples in the list?

``(fd, eventmask)`` tuples if there's any event. Otherwise, an empty list
is returned.

.. versionchanged:: 3.5
The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
:pep:`475` for the rationale), instead of raising
:exc:`InterruptedError`.

.. method:: epoll.close()

Expand All @@ -314,7 +283,7 @@ Edge and Level Trigger Polling (epoll) Objects

.. attribute:: epoll.closed

``True`` if the epoll object is closed.
Return ``True`` if the epoll object is closed.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should Return be used for an attribute? Maybe use Set to?



.. method:: epoll.fileno()
Expand All @@ -327,30 +296,65 @@ Edge and Level Trigger Polling (epoll) Objects
Create an epoll object from a given file descriptor.


.. method:: epoll.register(fd[, eventmask])

Register a fd descriptor with the epoll object.
.. method:: epoll.register(fd, eventmask=EPOLLIN | EPOLLOUT | EPOLLPRI)

Register a *fd* descriptor with the epoll object.

.. method:: epoll.modify(fd, eventmask)

Modify a registered file descriptor.
*eventmask* is an optional bitmask describing the type of events you want
to check for.


.. method:: epoll.unregister(fd)

Remove a registered file descriptor from the epoll object.


.. method:: epoll.poll(timeout=-1, maxevents=-1)
.. method:: epoll.modify(fd, eventmask)

Wait for events. timeout in seconds (float)
Modify a registered file descriptor.

.. versionchanged:: 3.5
The function is now retried with a recomputed timeout when interrupted by
a signal, except if the signal handler raises an exception (see
:pep:`475` for the rationale), instead of raising
:exc:`InterruptedError`.

The following constants can be used with
:meth:`~epoll.register` and :meth:`~epoll.modify` methods. See
:manpage:`epoll(4)` for more information.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if this table should be under epoll.register, similar to the section for poll.


+-------------------------+-----------------------------------------------+
| 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:`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 a fd. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDHUP` | Stream socket peer closed connection or shut |
| | down writing half of connection. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDNORM` | Equivalent to :const:`EPOLLIN` |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLRDBAND` | Priority data band can be read. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLWRNORM` | Equivalent to :const:`EPOLLOUT` |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLWRBAND` | Priority data may be written. |
+-------------------------+-----------------------------------------------+
| :const:`EPOLLMSG` | Ignored. |
+-------------------------+-----------------------------------------------+


.. _poll-objects:
Expand Down
2 changes: 1 addition & 1 deletion Modules/selectmodule.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1447,7 +1447,7 @@ PyDoc_STRVAR(pyepoll_register_doc,
\n\
Registers a new fd or raises an OSError if the fd is already registered.\n\
fd is the target file descriptor of the operation.\n\
events is a bit set composed of the various EPOLL constants; the default\n\
eventmask is a bit set composed of the various EPOLL constants; the default\n\
is EPOLLIN | EPOLLOUT | EPOLLPRI.\n\
\n\
The epoll interface supports all file descriptors that support poll.");
Expand Down