mirrors
/
micropython
mirror of https://github.com/micropython/micropython.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
micropython/docs/library/select.rst

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

100 lines
3.4 KiB
ReStructuredText
Raw Normal View History

docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
:mod:`select` -- wait for events on a set of streams
====================================================
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
.. module:: select
docs: select: Describe extra details.
2014-11-08 18:14:05 +00:00
:synopsis: wait for events on a set of streams
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/library: Add CPython docs xref to each pertinent module. Cross-reference text/link is implemented as RST substitution, so easy to consistently.
2017-07-02 13:37:31 +01:00
|see_cpython_module| :mod:`python:select`.
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
This module provides functions to efficiently wait for events on multiple
docs/library: Add xrefs to "stream" dictionary entry for many modules.
2017-12-04 16:36:20 +00:00
`streams <stream>` (select streams which are ready for operations).
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
Functions
---------
.. function:: poll()
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
Create an instance of the Poll class.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
.. function:: select(rlist, wlist, xlist[, timeout])
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
Wait for activity on a set of objects.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
This function is provided by some MicroPython ports for compatibility
and is not efficient. Usage of :class:`Poll` is recommended instead.
docs: select: Describe extra details.
2014-11-08 18:14:05 +00:00
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
.. _class: Poll
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
class ``Poll``
--------------
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
Methods
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
~~~~~~~
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
.. method:: poll.register(obj[, eventmask])
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/library: Add xrefs to "stream" dictionary entry for many modules.
2017-12-04 16:36:20 +00:00
Register `stream` *obj* for polling. *eventmask* is logical OR of:
docs/select: Document POLLIN/OUT/ERR/HUP.
2015-11-09 20:10:02 +00:00
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
* ``select.POLLIN`` - data available for reading
* ``select.POLLOUT`` - more data can be written
docs/select: Document POLLIN/OUT/ERR/HUP.
2015-11-09 20:10:02 +00:00
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
Note that flags like ``select.POLLHUP`` and ``select.POLLERR`` are
docs/uselect: Describe POLLHUP/POLLERR semantics in more details. 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.
2017-11-26 07:55:02 +00:00
*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.
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
*eventmask* defaults to ``select.POLLIN | select.POLLOUT``.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/uselect: Describe more aspects of poll.register/modify behavior. E.g., register() can be called again for the same object, while modify() will raise exception if object was not register()ed before.
2018-09-28 20:05:45 +01:00
It is OK to call this function multiple times for the same *obj*.
Successive calls will update *obj*'s eventmask to the value of
*eventmask* (i.e. will behave as `modify()`).
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
.. method:: poll.unregister(obj)
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
Unregister *obj* from polling.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
.. method:: poll.modify(obj, eventmask)
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/uselect: Describe more aspects of poll.register/modify behavior. E.g., register() can be called again for the same object, while modify() will raise exception if object was not register()ed before.
2018-09-28 20:05:45 +01:00
Modify the *eventmask* for *obj*. If *obj* is not registered, `OSError`
is raised with error of ENOENT.
docs: Import documentation from source-code inline comments. The inline docs (prefixed with /// in .c files) have been converted to RST format and put in the docs subdirectory.
2014-10-31 01:37:19 +00:00
docs/library: Add / to indicate positional-only args in library docs. Removes the confusion of positional-only arguments which have defaults that look like keyword arguments.
2020-01-11 06:44:17 +00:00
.. method:: poll.poll(timeout=-1, /)
docs: Cleanup and update some docs.
2014-10-31 22:21:37 +00:00
docs/uselect: Describe POLLHUP/POLLERR semantics in more details. 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.
2017-11-26 07:55:02 +00:00
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
docs: Replace ufoo with foo in all docs. Anywhere a module is mentioned, use its "non-u" name for consistency. The "import module" vs "import umodule" is something of a FAQ, and this commit intends to help clear that up. As a first approximation MicroPython is Python, and so imports should work the same as Python and use the same name, to a first approximation. The u-version of a module is a detail that can be learned later on, when the user wants to understand more and have finer control over importing. Existing Python code should just work, as much as it is possible to do that within the constraints of embedded systems, and the MicroPython documentation should match the idiomatic way to write Python code. With universal weak links for modules (via MICROPY_MODULE_WEAK_LINKS) users can consistently use "import foo" across all ports (with the exception of the minimal ports). And the ability to override/extend via "foo.py" continues to work well. Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
2021-08-12 04:59:29 +01:00
is a combination of ``select.POLL*`` constants described above. Note that
flags ``select.POLLHUP`` and ``select.POLLERR`` can be returned at any time
docs/uselect: Describe POLLHUP/POLLERR semantics in more details. 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.
2017-11-26 07:55:02 +00:00
(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.
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
.. admonition:: Difference to CPython
:class: attention
Tuples returned may contain more than 2 elements as described above.
docs/library: Add / to indicate positional-only args in library docs. Removes the confusion of positional-only arguments which have defaults that look like keyword arguments.
2020-01-11 06:44:17 +00:00
.. method:: poll.ipoll(timeout=-1, flags=0, /)
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
docs/glossary: Describe the callee-owned tuple concept.
2017-12-03 13:07:46 +00:00
Like :meth:`poll.poll`, but instead returns an iterator which yields a
`callee-owned tuple`. This function provides an efficient, allocation-free
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
way to poll on streams.
docs: Fix some spelling mistakes.
2021-04-30 07:53:36 +01:00
If *flags* is 1, one-shot behaviour for events is employed: streams for
docs/uselect: ipoll: Fix grammar/wording of one-shot flag description.
2017-11-30 18:32:49 +00:00
which events happened will have their event masks automatically reset
(equivalent to ``poll.modify(obj, 0)``), so new events for such a stream
won't be processed until new mask is set with `poll.modify()`. This
docs: Fix some spelling mistakes.
2021-04-30 07:53:36 +01:00
behaviour is useful for asynchronous I/O schedulers.
docs/uselect: Document one-shot polling mode.
2017-10-25 22:28:45 +01:00
docs/select: Rename to uselect, to match the actual module name. Also, add ipoll() documentation and markup changes to comply with CPython usage.
2017-06-16 09:28:06 +01:00
.. admonition:: Difference to CPython
:class: attention
This function is a MicroPython extension.