From 94696973a01059ffb370ada98f655b08de9b6302 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Fri, 16 Jun 2017 11:28:06 +0300 Subject: docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage. --- docs/library/index.rst | 7 +++-- docs/library/select.rst | 67 ------------------------------------------ docs/library/uselect.rst | 76 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 80 insertions(+), 70 deletions(-) delete mode 100644 docs/library/select.rst create mode 100644 docs/library/uselect.rst (limited to 'docs') diff --git a/docs/library/index.rst b/docs/library/index.rst index 770920a1f..e0260b701 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -72,7 +72,6 @@ it will fallback to loading the built-in ``ujson`` module. cmath.rst gc.rst math.rst - select.rst sys.rst ubinascii.rst ucollections.rst @@ -82,6 +81,7 @@ it will fallback to loading the built-in ``ujson`` module. ujson.rst uos.rst ure.rst + uselect.rst usocket.rst ustruct.rst utime.rst @@ -97,7 +97,6 @@ it will fallback to loading the built-in ``ujson`` module. cmath.rst gc.rst math.rst - select.rst sys.rst ubinascii.rst ucollections.rst @@ -107,6 +106,7 @@ it will fallback to loading the built-in ``ujson`` module. ujson.rst uos.rst ure.rst + uselect.rst usocket.rst ustruct.rst utime.rst @@ -120,12 +120,12 @@ it will fallback to loading the built-in ``ujson`` module. builtins.rst array.rst gc.rst - select.rst sys.rst ubinascii.rst ujson.rst uos.rst ure.rst + uselect.rst usocket.rst ussl.rst utime.rst @@ -148,6 +148,7 @@ it will fallback to loading the built-in ``ujson`` module. ujson.rst uos.rst ure.rst + uselect.rst usocket.rst ussl.rst ustruct.rst diff --git a/docs/library/select.rst b/docs/library/select.rst deleted file mode 100644 index 8dcd4080f..000000000 --- a/docs/library/select.rst +++ /dev/null @@ -1,67 +0,0 @@ -:mod:`select` -- wait for events on a set of streams -======================================================================== - -.. module:: select - :synopsis: wait for events on a set of streams - -This module provides functions to wait for events on streams (select streams -which are ready for operations). - -Pyboard specifics ------------------ - -Polling is an efficient way of waiting for read/write activity on multiple -objects. Current objects that support polling are: :class:`pyb.UART`, -:class:`pyb.USB_VCP`. - -Functions ---------- - -.. function:: poll() - - Create an instance of the Poll class. - -.. function:: select(rlist, wlist, xlist[, timeout]) - - Wait for activity on a set of objects. - - This function is provided for compatibility and is not efficient. Usage - of :class:`Poll` is recommended instead. - -.. _class: Poll - -class ``Poll`` --------------- - -Methods -~~~~~~~ - -.. method:: poll.register(obj[, eventmask]) - - 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 - - ``eventmask`` defaults to ``select.POLLIN | select.POLLOUT``. - -.. method:: poll.unregister(obj) - - Unregister ``obj`` from polling. - -.. method:: poll.modify(obj, eventmask) - - Modify the ``eventmask`` for ``obj``. - -.. method:: poll.poll([timeout]) - - Wait for at least one of the registered objects to become ready. 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. diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst new file mode 100644 index 000000000..68df9d381 --- /dev/null +++ b/docs/library/uselect.rst @@ -0,0 +1,76 @@ +:mod:`uselect` -- wait for events on a set of streams +======================================================================== + +.. module:: uselect + :synopsis: wait for events on a set of streams + +This module provides functions to efficiently wait for events on multiple +streams (select streams which are ready for operations). + +Functions +--------- + +.. function:: poll() + + Create an instance of the Poll class. + +.. function:: select(rlist, wlist, xlist[, timeout]) + + Wait for activity on a set of objects. + + This function is provided by some MicroPython ports for compatibility + and is not efficient. Usage of :class:`Poll` is recommended instead. + +.. _class: Poll + +class ``Poll`` +-------------- + +Methods +~~~~~~~ + +.. method:: poll.register(obj[, eventmask]) + + 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 + + *eventmask* defaults to ``select.POLLIN | select.POLLOUT``. + +.. method:: poll.unregister(obj) + + Unregister *obj* from polling. + +.. method:: poll.modify(obj, eventmask) + + Modify the *eventmask* for *obj*. + +.. method:: poll.poll([timeout]) + + Wait for at least one of the registered objects to become ready. 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. + + .. admonition:: Difference to CPython + :class: attention + + Tuples returned may contain more than 2 elements as described above. + +.. method:: poll.ipoll([timeout]) + + Like :meth:`poll.poll`, but instead returns an iterator which yields + callee-owned tuples. This function provides efficient, allocation-free + way to poll on streams. + + .. admonition:: Difference to CPython + :class: attention + + This function is a MicroPython extension. -- cgit v1.2.3