ringbuf_queue raises IndexError. Fix gather error in tutorial.

Author: peterhinch

v3/docs/EVENTS.md

@@ -500,9 +500,9 @@ 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_nowait` No arg. Returns an object from the queue. Raises an exception
+ * `get_nowait` No arg. Returns an object from the queue. Raises `IndexError`
  if the queue is empty.
- * `put_nowait` Arg: the object to put on the queue. Raises an exception if the
+ * `put_nowait` Arg: the object to put on the queue. Raises `IndexError` if the
  queue is full. If the calling code ignores the exception the oldest item in
  the queue will be overwritten. In some applications this can be of use.
 
@@ -523,6 +523,17 @@ async def handle_queued_data(q):
 The `sleep` is necessary if you have multiple tasks waiting on the queue,
 otherwise one task hogs all the data.
 
+The following illustrates putting items onto a `RingbufQueue` where the queue is
+not allowed to stall: where it becomes full, new items overwrite the oldest ones
+in the queue:
+```python
+def add_item(q, data):
+try:
+    q.put_nowait(data)
+except IndexError:
+    pass
+```
+
 ###### [Contents](./EVENTS.md#0-contents)
 
 # 100 Appendix 1 Polling

v3/docs/TUTORIAL.md

@@ -755,7 +755,7 @@ cancellation or timeout. It returns a list of the return values of each task.
 
 Its call signature is
 ```python
-res = await asyncio.gather(*tasks, return_exceptions=True)
+res = await asyncio.gather(*tasks, return_exceptions=False)
 ```
 The keyword-only boolean arg `return_exceptions` determines the behaviour in
 the event of a cancellation or timeout of tasks. If `False`, the `gather`
@@ -1095,10 +1095,25 @@ serviced the device, the ISR flags an asynchronous routine, typically
 processing received data.
 
 The fact that only one task may wait on a `ThreadSafeFlag` may be addressed by
-having the task that waits on the `ThreadSafeFlag` set an `Event`. Multiple
-tasks may wait on that `Event`. As an alternative to explicitly coding this,
-the [Message class](./TUTORIAL.md#39-message) uses this approach to provide an
-`Event`-like object which can be triggered from an ISR.
+having a task that waits on the `ThreadSafeFlag` set an `Event` as in the
+following:
+```python
+class ThreadSafeEvent(asyncio.Event):
+    def __init__(self):
+        super().__init__()
+        self._tsf = asyncio.ThreadSafeFlag()
+        asyncio.create_task(self._run())
+
+    async def _run(self):
+        while True:
+            await self._tsf.wait()
+            super().set()
+
+    def set(self):
+        self._tsf.set()
+```
+An instance may be set by a hard ISR or from another thread/core. It must
+explicitly be cleared. Multiple tasks may wait on it.
 
 ###### [Contents](./TUTORIAL.md#contents)
 

v3/primitives/ringbuf_queue.py

@@ -6,13 +6,6 @@
 
 import uasyncio as asyncio
 
-# Exception raised by get_nowait().
-class QueueEmpty(Exception):
-    pass
-
-# Exception raised by put_nowait().
-class QueueFull(Exception):
-    pass
 
 class RingbufQueue:  # MicroPython optimised
     def __init__(self, buf):
@@ -35,7 +28,7 @@ def qsize(self):
     def get_nowait(self):  # Remove and return an item from the queue.
         # Return an item if one is immediately available, else raise QueueEmpty.
         if self.empty():
-            raise QueueEmpty()
+            raise IndexError
         r = self._q[self._ri]
         self._ri = (self._ri + 1) % self._size
         return r
@@ -47,7 +40,7 @@ def put_nowait(self, v):
         self._wi = (self._wi + 1) % self._size
         if self._wi == self._ri:  # Would indicate empty
             self._ri = (self._ri + 1) % self._size  # Discard a message
-            raise QueueFull  # Caller can ignore if overwrites are OK
+            raise IndexError  # Caller can ignore if overwrites are OK
 
     async def put(self, val):  # Usage: await queue.put(item)
         while self.full():  # Queue full

v3/primitives/tests/asyntest.py

@@ -533,7 +533,7 @@ async def rbq_go():
     for x in range(4, 15):
         try:
             q.put_nowait(x)
-        except:
+        except IndexError:
             nfail += 1
     assert nfail == 5
     assert q.full()