RingbufQueue: add peek synchronous method.

Author: peterhinch

v3/docs/EVENTS.md

@@ -507,6 +507,8 @@ Synchronous methods (immediate return):
  * `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.
+ * `peek` No arg. Returns oldest entry without removing it from the queue. This
+ is a superset of the CPython compatible methods.
 
 Asynchronous methods:  
  * `put` Arg: the object to put on the queue. If the queue is full, it will

v3/primitives/ringbuf_queue.py

@@ -39,6 +39,12 @@ def get_nowait(self):  # Remove and return an item from the queue.
         self._evget.clear()
         return r
 
+    def peek(self):  # Return oldest item from the queue without removing it.
+        # Return an item if one is immediately available, else raise QueueEmpty.
+        if self.empty():
+            raise IndexError
+        return self._q[self._ri]
+
     def put_nowait(self, v):
         self._q[self._wi] = v
         self._evput.set()  # Schedule any tasks waiting on get