Code improvements to ThreadSafeQueue. Fix docs and code comments.

Author: peterhinch

v3/docs/EVENTS.md

@@ -536,9 +536,9 @@ except IndexError:
 
 # 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.
+This queue is designed to interface between one `uasyncio` task and a single
+thread running in a different context. This can be an interrupt service routine
+(ISR), code running in a different thread or code 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`
@@ -556,7 +556,7 @@ 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):  
+Synchronous methods.  
  * `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.
@@ -567,6 +567,9 @@ Synchronous methods (immediate return):
  `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.
 
+The blocking methods should not be used in the `uasyncio` context, because by
+blocking they will lock up the scheduler.
+
 Asynchronous methods:  
  * `put` Arg: the object to put on the queue. If the queue is full, it will
  block until space is available.
@@ -579,12 +582,8 @@ 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):

v3/primitives/threadsafe_queue.py

@@ -5,7 +5,6 @@
 
 # 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
 
@@ -29,41 +28,36 @@ 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
+        if not block and self.empty():
+            raise IndexError  # Not allowed to block
+        while self.empty():  # Block until an item appears
+            pass
         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:
+        self._evput.set()  # Schedule task waiting on get
+        if not block and self.full():
             raise IndexError
+        while self.full():
+            pass  # can't bump ._wi until an item is removed
         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
+            await self._evget.wait()
         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
+        while self.empty():
             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
+        self._evget.set()  # Schedule task waiting on ._evget
         return r