Fix RingbufQueue bug. Add ThreadSafeQueue.

Author: peterhinch

v3/docs/EVENTS.md

@@ -534,6 +534,85 @@ except IndexError:
     pass
 ```
 
+# 8. Threadsafe Queue
+
+This queue is designed to interface between one or more `uasyncio` tasks and a
+single thread running in a different context. This can be an interrupt service
+routine (ISR) or code running in a different thread or on a different core.
+
+Any Python object may be placed on a `ThreadSafeQueue`. If bi-directional
+communication is required between the two contexts, two `ThreadSafeQueue`
+instances are required.
+
+Attributes of `ThreadSafeQueue`:
+ 1. It is of fixed size defined on instantiation.
+ 2. It uses pre-allocated buffers of various types (`Queue` uses a `list`).
+ 3. It is an asynchronous iterator allowing retrieval with `async for`.
+ 4. It provides synchronous "put" and "get" methods. If the queue becomes full
+ (put) or empty (get), behaviour is user definable. The method either blocks or
+ raises an `IndexError`.
+
+Constructor mandatory arg:
+ * `buf` Buffer for the queue, e.g. list `[0 for _ in range(20)]` or array. A
+ buffer of size `N` can hold a maximum of `N-1` items.
+
+Synchronous methods (immediate return):  
+ * `qsize` No arg. Returns the number of items in the queue.
+ * `empty` No arg. Returns `True` if the queue is empty.
+ * `full` No arg. Returns `True` if the queue is full.
+ * `get_sync` Arg `block=False`. Returns an object from the queue. Raises
+ `IndexError` if the queue is empty, unless `block==True` in which case the
+ method blocks until the `uasyncio` tasks put an item on the queue.
+ * `put_sync` Args: the object to put on the queue, `block=False`. Raises
+ `IndexError` if the  queue is full unless `block==True` in which case the
+ method blocks until the `uasyncio` tasks remove an item from the queue.
+
+Asynchronous methods:  
+ * `put` Arg: the object to put on the queue. If the queue is full, it will
+ block until space is available.
+
+In use as a data consumer the `uasyncio` code will use `async for` to retrieve
+items from the queue. If it is a data provider it will use `put` to place
+objects on the queue.
+
+Data consumer:
+```python
+async def handle_queued_data(q):
+    async for obj in q:
+        await asyncio.sleep(0)  # See below
+        # Process obj
+```
+The `sleep` is necessary if you have multiple tasks waiting on the queue,
+otherwise one task hogs all the data.
+
+Data provider:
+```python
+async def feed_queue(q):
+    while True:
+        data = await data_source()
+        await q.put(data)
+```
+The alternate thread will use synchronous methods.
+
+Data provider (throw if full):
+```python
+while True:
+    data = data_source()
+    try:
+        q.put_sync(data)
+    except IndexError:
+        # Queue is full
+```
+Data consumer (block while empty):
+```python
+while True:
+    data = q.get(block=True)  # May take a while if the uasyncio side is slow
+    process(data)  # Do something with it
+```
+Note that where the alternate thread is an ISR it is very bad practice to allow
+blocking. The application should be designed in such a way that the full/empty
+case does not occur.
+
 ###### [Contents](./EVENTS.md#0-contents)
 
 # 100 Appendix 1 Polling

v3/primitives/__init__.py

@@ -48,6 +48,7 @@ def _handle_exception(loop, context):
     "ESwitch": "events",
     "EButton": "events",
     "RingbufQueue": "ringbuf_queue",
+    "ThreadSafeQueue": "threadsafe_queue",
 }
 
 # Copied from uasyncio.__init__.py

v3/primitives/ringbuf_queue.py

@@ -1,4 +1,8 @@
 # ringbuf_queue.py Provides RingbufQueue class
+
+# Copyright (c) 2022 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
 # API differs from CPython
 # Uses pre-allocated ring buffer: can use list or array
 # Asynchronous iterator allowing consumer to use async for
@@ -31,6 +35,8 @@ def get_nowait(self):  # Remove and return an item from the queue.
             raise IndexError
         r = self._q[self._ri]
         self._ri = (self._ri + 1) % self._size
+        self._evget.set()  # Schedule all tasks waiting on ._evget
+        self._evget.clear()
         return r
 
     def put_nowait(self, v):

v3/primitives/threadsafe_queue.py

@@ -0,0 +1,69 @@
+# threadsafe_queue.py Provides ThreadsafeQueue class
+
+# Copyright (c) 2022 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+# Uses pre-allocated ring buffer: can use list or array
+# Asynchronous iterator allowing consumer to use async for
+# put_nowait QueueFull exception can be ignored allowing oldest data to be discarded.
+
+import uasyncio as asyncio
+
+
+class ThreadSafeQueue:  # MicroPython optimised
+    def __init__(self, buf):
+        self._q = buf
+        self._size = len(buf)
+        self._wi = 0
+        self._ri = 0
+        self._evput = asyncio.ThreadSafeFlag()  # Triggered by put, tested by get
+        self._evget = asyncio.ThreadSafeFlag()  # Triggered by get, tested by put
+
+    def full(self):
+        return ((self._wi + 1) % self._size) == self._ri
+
+    def empty(self):
+        return self._ri == self._wi
+
+    def qsize(self):
+        return (self._wi - self._ri) % self._size
+
+    def get_sync(self, block=False):  # Remove and return an item from the queue.
+        # Return an item if one is immediately available, else raise QueueEmpty.
+        if block:
+            while self.empty():
+                pass
+        else:
+            if self.empty():
+                raise IndexError
+        r = self._q[self._ri]
+        self._ri = (self._ri + 1) % self._size
+        self._evget.set()
+        return r
+
+    def put_sync(self, v, block=False):
+        self._q[self._wi] = v
+        self._evput.set()  # Schedule any tasks waiting on get
+        if block:
+            while ((self._wi + 1) % self._size) == self._ri:
+                pass  # can't bump ._wi until an item is removed
+        elif ((self._wi + 1) % self._size) == self._ri:
+            raise IndexError
+        self._wi = (self._wi + 1) % self._size
+
+    async def put(self, val):  # Usage: await queue.put(item)
+        while self.full():  # Queue full
+            await self._evget.wait()  # May be >1 task waiting on ._evget
+            # Task(s) waiting to get from queue, schedule first Task
+        self.put_sync(val)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        while self.empty():  # Empty. May be more than one task waiting on ._evput
+            await self._evput.wait()
+        r = self._q[self._ri]
+        self._ri = (self._ri + 1) % self._size
+        self._evget.set()  # Schedule all tasks waiting on ._evget
+        return r