djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Paul Sokolovsky 2017-11-26 09:55:02 +02:00
parent 50cffcfe2c
commit f59c6b48ae
1 changed files with 22 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
docs/library/uselect.rst
View File

@ -35,12 +35,15 @@ Methods
Register *obj* for polling. *eventmask* is logical OR of: Register *obj* for polling. *eventmask* is logical OR of:
* ``select.POLLIN`` - data available for reading * `uselect.POLLIN` - data available for reading
* ``select.POLLOUT`` - more data can be written * `uselect.POLLOUT` - more data can be written
* ``select.POLLERR`` - error occurred
* ``select.POLLHUP`` - end of stream/connection termination detected
*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) .. method:: poll.unregister(obj)
@ -52,15 +55,21 @@ Methods
.. method:: poll.poll(timeout=-1) .. method:: poll.poll(timeout=-1)
Wait for at least one of the registered objects to become ready, with optional Wait for at least one of the registered objects to become ready or have an
timeout in milliseconds (if *timeout* arg is not specified or -1, there is no exceptional condition, with optional timeout in milliseconds (if *timeout*
timeout). Returns list of (``obj``, ``event``, ...) tuples, ``event`` element specifies arg is not specified or -1, there is no timeout).
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. 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 .. admonition:: Difference to CPython
:class: attention :class: attention