cocotb 1.9.2__cp312-cp312-win32.whl → 2.0.0rc2__cp312-cp312-win32.whl

cocotb/queue.py

@@ -4,24 +4,42 @@
 import asyncio.queues
 import collections
 import heapq
-from typing import Generic, TypeVar
+from abc import abstractmethod
+from typing import (
+    Deque,
+    Generic,
+    List,
+    Tuple,
+    TypeVar,
+)
 
 import cocotb
-from cocotb.triggers import Event, _pointer_str
+from cocotb._utils import pointer_str
+from cocotb.task import Task
+from cocotb.triggers import Event
+
+__all__ = (
+    "AbstractQueue",
+    "LifoQueue",
+    "PriorityQueue",
+    "Queue",
+    "QueueEmpty",
+    "QueueFull",
+)
 
 
 class QueueFull(asyncio.queues.QueueFull):
-    """Raised when the Queue.put_nowait() method is called on a full Queue."""
+    """Raised when the :meth:`Queue.put_nowait()` method is called on a full :class:`Queue`."""
 
 
 class QueueEmpty(asyncio.queues.QueueEmpty):
-    """Raised when the Queue.get_nowait() method is called on a empty Queue."""
+    """Raised when the :meth:`Queue.get_nowait()` method is called on an empty :class:`Queue`."""
 
 
 T = TypeVar("T")
 
 
-class Queue(Generic[T]):
+class AbstractQueue(Generic[T]):
     """A queue, useful for coordinating producer and consumer coroutines.
 
     If *maxsize* is less than or equal to 0, the queue size is infinite. If it
@@ -29,58 +47,53 @@ class Queue(Generic[T]):
     reaches *maxsize*, until an item is removed by :meth:`get`.
     """
 
-    def __init__(self, maxsize: int = 0):
-
-        self._maxsize = maxsize
-
-        self._finished = Event()
-        self._finished.set()
+    def __init__(self, maxsize: int = 0) -> None:
+        self._maxsize: int = maxsize
+        self._getters: Deque[Tuple[Event, Task[object]]] = collections.deque()
+        self._putters: Deque[Tuple[Event, Task[object]]] = collections.deque()
 
-        self._getters = collections.deque()
-        self._putters = collections.deque()
+    @abstractmethod
+    def _get(self) -> T:
+        """Remove and return the next element from the queue."""
 
-        self._init(maxsize)
+    @abstractmethod
+    def _put(self, item: T) -> None:
+        """Place a new element on the queue."""
 
-    def _init(self, maxsize):
-        self._queue = collections.deque()
+    @abstractmethod
+    def _size(self) -> int:
+        """Return the number of elements in the queue."""
 
-    def _put(self, item):
-        self._queue.append(item)
-
-    def _get(self):
-        return self._queue.popleft()
+    @abstractmethod
+    def _repr(self) -> str:
+        """Return a string representation of the state of the queue."""
 
-    def _wakeup_next(self, waiters):
+    def _wakeup_next(self, waiters: Deque[Tuple[Event, Task[object]]]) -> None:
         while waiters:
             event, task = waiters.popleft()
             if not task.done():
                 event.set()
                 break
 
-    def __repr__(self):
-        return "<{} {} at {}>".format(
-            type(self).__name__, self._format(), _pointer_str(self)
-        )
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self._format()} at {pointer_str(self)}>"
 
-    def __str__(self):
-        return "<{} {}>".format(type(self).__name__, self._format())
+    def __str__(self) -> str:
+        return f"<{type(self).__name__} {self._format()}>"
 
-    def __class_getitem__(cls, type):
-        return cls
-
-    def _format(self):
-        result = "maxsize={}".format(repr(self._maxsize))
+    def _format(self) -> str:
+        result = f"maxsize={self._maxsize!r}"
         if getattr(self, "_queue", None):
-            result += " _queue={}".format(repr(list(self._queue)))
+            result += f" _queue={self._repr()}"
         if self._getters:
-            result += " _getters[{}]".format(len(self._getters))
+            result += f" _getters[{len(self._getters)}]"
         if self._putters:
-            result += " _putters[{}]".format(len(self._putters))
+            result += f" _putters[{len(self._putters)}]"
         return result
 
     def qsize(self) -> int:
         """Number of items in the queue."""
-        return len(self._queue)
+        return self._size()
 
     @property
     def maxsize(self) -> int:
@@ -89,7 +102,7 @@ class Queue(Generic[T]):
 
     def empty(self) -> bool:
         """Return ``True`` if the queue is empty, ``False`` otherwise."""
-        return not self._queue
+        return self._size() == 0
 
     def full(self) -> bool:
         """Return ``True`` if there are :meth:`maxsize` items in the queue.
@@ -110,20 +123,19 @@ class Queue(Generic[T]):
         slot is available before adding the item.
         """
         while self.full():
-            event = Event("{} put".format(type(self).__name__))
-            self._putters.append((event, cocotb.scheduler._current_task))
+            event = Event()
+            self._putters.append((event, cocotb.task.current_task()))
             await event.wait()
         self.put_nowait(item)
 
     def put_nowait(self, item: T) -> None:
         """Put an *item* into the queue without blocking.
 
-        If no free slot is immediately available, raise :exc:`asyncio.QueueFull`.
+        If no free slot is immediately available, raise :exc:`~cocotb.queue.QueueFull`.
         """
         if self.full():
             raise QueueFull()
         self._put(item)
-        self._finished.clear()
         self._wakeup_next(self._getters)
 
     async def get(self) -> T:
@@ -132,8 +144,8 @@ class Queue(Generic[T]):
         If the queue is empty, wait until an item is available.
         """
         while self.empty():
-            event = Event("{} get".format(type(self).__name__))
-            self._getters.append((event, cocotb.scheduler._current_task))
+            event = Event()
+            self._getters.append((event, cocotb.task.current_task()))
             await event.wait()
         return self.get_nowait()
 
@@ -141,7 +153,7 @@ class Queue(Generic[T]):
         """Remove and return an item from the queue.
 
         Return an item if one is immediately available, else raise
-        :exc:`asyncio.QueueEmpty`.
+        :exc:`~cocotb.queue.QueueEmpty`.
         """
         if self.empty():
             raise QueueEmpty()
@@ -150,30 +162,64 @@ class Queue(Generic[T]):
         return item
 
 
-class PriorityQueue(Queue):
-    r"""A subclass of :class:`Queue`; retrieves entries in priority order (smallest item first).
+class Queue(AbstractQueue[T]):
+    """A subclass of :class:`AbstractQueue`; retrieves oldest entries first (FIFO)."""
+
+    def __init__(self, maxsize: int = 0) -> None:
+        super().__init__(maxsize)
+        self._queue: Deque[T] = collections.deque()
+
+    def _put(self, item: T) -> None:
+        self._queue.append(item)
+
+    def _get(self) -> T:
+        return self._queue.popleft()
+
+    def _size(self) -> int:
+        return len(self._queue)
+
+    def _repr(self) -> str:
+        return repr(self._queue)
+
+
+class PriorityQueue(AbstractQueue[T]):
+    r"""A subclass of :class:`AbstractQueue`; retrieves entries in priority order (smallest item first).
 
     Entries are typically tuples of the form ``(priority number, data)``.
     """
 
-    def _init(self, maxsize):
-        self._queue = []
+    def __init__(self, maxsize: int = 0) -> None:
+        super().__init__(maxsize)
+        self._queue: List[T] = []
 
-    def _put(self, item):
+    def _put(self, item: T) -> None:
         heapq.heappush(self._queue, item)
 
-    def _get(self):
+    def _get(self) -> T:
         return heapq.heappop(self._queue)
 
+    def _size(self) -> int:
+        return len(self._queue)
+
+    def _repr(self) -> str:
+        return repr(self._queue)
+
 
-class LifoQueue(Queue):
-    """A subclass of :class:`Queue`; retrieves most recently added entries first."""
+class LifoQueue(AbstractQueue[T]):
+    """A subclass of :class:`AbstractQueue`; retrieves most recently added entries first (LIFO)."""
 
-    def _init(self, maxsize):
-        self._queue = collections.deque()
+    def __init__(self, maxsize: int = 0) -> None:
+        super().__init__(maxsize)
+        self._queue: Deque[T] = collections.deque()
 
-    def _put(self, item):
+    def _put(self, item: T) -> None:
         self._queue.append(item)
 
-    def _get(self):
+    def _get(self) -> T:
         return self._queue.pop()
+
+    def _size(self) -> int:
+        return len(self._queue)
+
+    def _repr(self) -> str:
+        return repr(self._queue)