bpo-33649: First asyncio docs improvement pass (GH-9142)

Rewritten/updated sections:

* Event Loop APIs
* Transports & Protocols
* Streams
* Exceptions
* Policies
* Queues
* Subprocesses
* Platforms

1 files changed, 105 insertions, 0 deletions

diff --git a/Doc/library/asyncio-platforms.rst b/Doc/library/asyncio-platforms.rst
new file mode 100644
index 0000000..afdbce6
--- /dev/null
+++ b/Doc/library/asyncio-platforms.rst
@@ -0,0 +1,105 @@
+.. currentmodule:: asyncio
+
+
+.. _asyncio-platform-support:
+
+
+=================
+Platforms Support
+=================
+
+The :mod:`asyncio` module has been designed to be portable,
+but some platforms have subtle differences and limitations.
+
+
+All Platforms
+=============
+
+* :meth:`loop.add_reader` and :meth:`loop.add_writer`
+  cannot be used to monitor file IO.
+
+
+Windows
+=======
+
+All event loops on Windows do not support the following methods:
+
+* :meth:`loop.create_unix_connection` and
+  :meth:`loop.create_unix_server` are not supported.
+  The :data:`socket.AF_UNIX` socket family is specific to UNIX/
+
+* :meth:`loop.add_signal_handler` and
+  :meth:`loop.remove_signal_handler` are not supported.
+
+:class:`SelectorEventLoop` has the following limitations:
+
+* :class:`~selectors.SelectSelector` is used to wait on socket events:
+  it supports sockets and is limited to 512 sockets.
+
+* :meth:`loop.add_reader` and :meth:`loop.add_writer` only accept
+  socket handles (e.g. pipe file descriptors are not supported).
+
+* Pipes are not supported, so the :meth:`loop.connect_read_pipe`
+  and :meth:`loop.connect_write_pipe` methods are not implemented.
+
+* :ref:`Subprocesses <asyncio-subprocess>` are not supported, i.e.
+  :meth:`loop.subprocess_exec` and :meth:`loop.subprocess_shell`
+  methods are not implemented.
+
+:class:`ProactorEventLoop` has the following limitations:
+
+* The :meth:`loop.create_datagram_endpoint` method
+  is not supported.
+
+* The :meth:`loop.add_reader` and :meth:`loop.add_writer`
+  methods are not supported.
+
+The resolution of the monotonic clock on Windows is usually around 15.6
+msec.  The best resolution is 0.5 msec. The resolution depends on the
+hardware (availability of `HPET
+<https://en.wikipedia.org/wiki/High_Precision_Event_Timer>`_) and on the
+Windows configuration.
+
+
+.. _asyncio-windows-subprocess:
+
+Subprocess Support on Windows
+-----------------------------
+
+:class:`SelectorEventLoop` on Windows does not support subproceses,
+so :class:`ProactorEventLoop` should be used instead::
+
+  import asyncio
+
+  asyncio.set_event_loop_policy(
+      asyncio.WindowsProactorEventLoopPolicy())
+
+  asyncio.run(your_code())
+
+
+The :meth:`policy.set_child_watcher()
+<AbstractEventLoopPolicy.set_child_watcher>` function is also
+not supported, as :class:`ProactorEventLoop` has a different mechanism
+to watch child processes.
+
+
+macOS
+=====
+
+Modern macOS versions are fully supported.
+
+.. rubric:: macOS <= 10.8
+
+On macOS 10.6, 10.7 and 10.8, the default event loop
+uses :class:`selectors.KqueueSelector`, which does not support
+character devices on these versions.  The :class:`SelectorEventLoop`
+can be manually configured to use :class:`~selectors.SelectSelector`
+or :class:`~selectors.PollSelector` to support character devices on
+these older versions of macOS.  Example::
+
+    import asyncio
+    import selectors
+
+    selector = selectors.SelectSelector()
+    loop = asyncio.SelectorEventLoop(selector)
+    asyncio.set_event_loop(loop)