Merge pull request #23 from dls-controls/asyncio_docs

Clarify asyncio vs cothread

Author: coretl

docs/explanations/asyncio-cothread-differences.rst

@@ -0,0 +1,98 @@
+What are the differences between `asyncio` and `cothread`?
+==========================================================
+
+There are two concurrency frameworks that pythonSoftIOC supports, `asyncio` and
+`cothread`. This page details the differences between them and reasons why you
+should use one over the other
+
+.. seealso::
+
+    `../how-to/use-asyncio-in-an-ioc` for an example of how to use asyncio and
+    pythonSoftIOC
+
+
+The Similarities
+----------------
+
+Both frameworks are asynchronous concurrency frameworks, which means that they
+run in a single OS thread, and use lightweight coroutines/cothreads for
+concurrency. These are more deterministic and use less resources than OS
+threads, which makes them well suited to applications like pythonSoftIOC where
+many records may be processing concurrently. The biggest advantage is that only
+one coroutine runs at any one time. A coroutine will run until it yields control
+to another coroutine. This means that changes to shared state can only occur
+when it has yielded control, which reduces the need for mutexes that would be
+needed in threaded code.
+
+
+The Differences
+---------------
+
+The main difference between the libraries is how a coroutine yields control.
+
+- `asyncio` uses an ``async def`` which will yield control when they ``await``.
+  Only an ``async def`` can ``await`` another ``async def``, so functions that
+  yield control are explicitly marked as such by the presence of the ``async``
+  keyword.
+- `cothread` has the :func:`~cothread.Yield` function which can be used in any
+  ordinary ``def``. The yield is implicit as you need to read the
+  documentation/source code to find out if a function will yield control
+
+For example, an `on_update` function written using cothread might be::
+
+    import cothread
+    from softioc import builder
+
+    def something_that_yields_control(value):
+        cothread.Sleep(0.1)
+
+    def update_ao(value):
+        something_that_yields_control(value)
+        print(value)
+
+    builder.aOut('AO', on_update=update_ao)
+
+While the same example written using asyncio is::
+
+    import asyncio
+    from softioc import builder
+
+    async def something_that_yields_control(value):
+        await asyncion.sleep(0.1)
+
+    async def update_ao(value):
+        await something_that_yields_control(value)
+        print(value)
+
+    builder.aOut('AO', on_update=update_ao)
+
+Note that because ``something_that_yields_control()`` is an ``async def``,
+``update_ao()`` needs to be too.
+
+.. seealso::
+
+    https://glyph.twistedmatrix.com/2014/02/unyielding.html for a discussion on
+    explicit vs implicit yield
+
+
+Which to use
+------------
+
+There are some questions to ask to help you choose which one to use:
+
+- If you run python2.7 then you need to use `cothread` as `asyncio` is python3
+  only
+- If you run on Windows then you need `asyncio` as `cothread` doesn't work on
+  Windows
+- If you need to integrate with a library that uses `asyncio` like one from
+  aio-libs_ then use `asyncio`
+- If you need to turn a script using `cothread.catools` into an IOC then use
+  `cothread`
+
+In general, avoid mixing concurrency frameworks if you can. While it is possible
+to mix `asyncio` and `cothread`, it's messy and tricky to get right. Better to
+keep to one if possible.
+
+.. _aio-libs: https://github.com/aio-libs
+
+

docs/how-to/use-asyncio-in-an-ioc.rst

@@ -1,16 +1,19 @@
 Use `asyncio` in an IOC
 =======================
 
-There are two libraries available for asynchronous operations in pythonSoftIOC:
-`cothread` and `asyncio`. This guide shows how to use the latter in
-an IOC.
+`../tutorials/creating-an-ioc` shows how to create a pythonSoftIOC using the
+`cothread` library. This page shows how to create one using `asyncio`
 
-.. note::
-    This page only explains the differences between using `cothread` and `asyncio`.
-    For more thorough explanation of the IOC itself see `../tutorials/creating-an-ioc`
+.. seealso::
+
+    `../explanations/asyncio-cothread-differences` for the differences and why
+    you would use one over the other
 
-.. literalinclude:: ../examples/example_asyncio_ioc.py
 
+Example IOC
+-----------
+
+.. literalinclude:: ../examples/example_asyncio_ioc.py
 
 The ``dispatcher`` is created and passed to :func:`~softioc.softioc.iocInit`. This is what
 allows the use of `asyncio` functions in this IOC. It contains a new event loop to handle

docs/index.rst

@@ -69,6 +69,7 @@ Table Of Contents
     :maxdepth: 1
 
     explanations/why-use-pythonSoftIOC
+    explanations/asyncio-cothread-differences
 
 .. rst-class:: no-margin-after-ul