docs/uselect: Describe POLLHUP/POLLERR semantics in more details.

pfalcon · pfalcon · commit f59c6b48aed7 · 2017-11-26T09:58:19.000+02:00
Per POSIX, http://pubs.opengroup.org/onlinepubs/9699919799/functions/poll.html these flags aren't valid in the input eventmask. Instead, they can be returned in unsolicited manner in the output eventmask at any time.
diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst
@@ -35,12 +35,15 @@ Methods
 
    Register *obj* for polling. *eventmask* is logical OR of:
 
-   * ``select.POLLIN``  - data available for reading
-   * ``select.POLLOUT`` - more data can be written
-   * ``select.POLLERR`` - error occurred
-   * ``select.POLLHUP`` - end of stream/connection termination detected
+   * `uselect.POLLIN`  - data available for reading
+   * `uselect.POLLOUT` - more data can be written
 
-   *eventmask* defaults to ``select.POLLIN | select.POLLOUT``.
+   Note that flags like `uselect.POLLHUP` and `uselect.POLLERR` are
+   *not* valid as input eventmask (these are unsolicited events which
+   will be returned from `poll()` regardless of whether they are asked
+   for). This semantics is per POSIX.
+
+   *eventmask* defaults to ``uselect.POLLIN | uselect.POLLOUT``.
 
 .. method:: poll.unregister(obj)
 
@@ -52,15 +55,21 @@ Methods
 
 .. method:: poll.poll(timeout=-1)
 
-   Wait for at least one of the registered objects to become ready, with optional
-   timeout in milliseconds (if *timeout* arg is not specified or -1, there is no
-   timeout). Returns list of (``obj``, ``event``, ...) tuples, ``event`` element specifies
-   which events happened with a stream and is a combination of ``select.POLL*``
-   constants described above. There may be other elements in tuple, depending
-   on a platform and version, so don't assume that its size is 2. In case of
-   timeout, an empty list is returned.
-
-   Timeout is in milliseconds.
+   Wait for at least one of the registered objects to become ready or have an
+   exceptional condition, with optional timeout in milliseconds (if *timeout*
+   arg is not specified or -1, there is no timeout).
+
+   Returns list of (``obj``, ``event``, ...) tuples. There may be other elements in
+   tuple, depending on a platform and version, so don't assume that its size is 2.
+   The ``event`` element specifies which events happened with a stream and
+   is a combination of ``uselect.POLL*`` constants described above. Note that
+   flags `uselect.POLLHUP` and `uselect.POLLERR` can be returned at any time
+   (even if were not asked for), and must be acted on accordingly (the
+   corresponding stream unregistered from poll and likely closed), because
+   otherwise all further invocations of `poll()` may return immediately with
+   these flags set for this stream again.
+
+   In case of timeout, an empty list is returned.
 
    .. admonition:: Difference to CPython
       :class: attention
