pkstruct 0.1.0__py3-none-any.whl

pkstruct/linear/queues/circular_queue.py

@@ -0,0 +1,258 @@
+"""
+pkstruct.linear.queues.circular_queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A fixed-capacity FIFO queue backed by a ring buffer (circular array).
+
+``CircularQueue`` uses a pre-allocated Python ``list`` with head and tail
+pointers that wrap around.  Enqueue and dequeue are O(1).  Once the buffer
+is full, further enqueue operations raise ``QueueFullError``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TypeVar
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.queues.queue import Queue
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+
+class QueueFullError(IndexError):
+    """Raised when attempting to enqueue into a full ``CircularQueue``."""
+
+    def __init__(self, capacity: int) -> None:
+        self.capacity: int = capacity
+        super().__init__(f"Queue is at capacity ({capacity}).")
+
+
+class CircularQueue(Queue[T]):
+    """
+    A thread-safe, fixed-capacity FIFO queue using a ring buffer.
+
+    The underlying ``list`` is allocated once at creation.  Head and tail
+    indices advance modulo capacity, avoiding the O(n) cost of shifting
+    elements.
+
+    Parameters
+    ----------
+    capacity:
+        Maximum number of elements the queue can hold.
+    items:
+        Optional iterable of initial values (front-to-rear order).
+        ``len(items)`` must not exceed *capacity*.
+
+    Examples
+    --------
+    >>> q = CircularQueue(3, [1, 2])
+    >>> q.enqueue(3)
+    >>> q.dequeue()
+    1
+    >>> q.front()
+    2
+    """
+
+    __slots__ = ("_buffer", "_capacity", "_head", "_tail", "_size", "_lock")
+
+    def __init__(self, capacity: int, items: list[T] | None = None) -> None:
+        if not isinstance(capacity, int) or capacity < 1:
+            raise ValueError(f"Capacity must be a positive integer, got {capacity!r}.")
+        self._capacity: int = capacity
+        self._buffer: list[T | None] = [None] * capacity
+        self._head: int = 0
+        self._tail: int = 0
+        self._size: int = 0
+        self._lock: StructureLock = StructureLock()
+        if items is not None:
+            if len(items) > capacity:
+                raise ValueError(
+                    f"Initial items ({len(items)}) exceeds capacity ({capacity})."
+                )
+            for item in items:
+                self._enqueue_unsafe(item)
+
+    # ------------------------------------------------------------------ #
+    #  Internal helpers                                                    #
+    # ------------------------------------------------------------------ #
+
+    def _enqueue_unsafe(self, value: T) -> None:
+        """Enqueue without acquiring the lock or full-check (caller must hold lock)."""
+        self._buffer[self._tail] = value
+        self._tail = (self._tail + 1) % self._capacity
+        self._size += 1
+
+    def _next_index(self, index: int) -> int:
+        """Return the next index modulo capacity."""
+        return (index + 1) % self._capacity
+
+    def _prev_index(self, index: int) -> int:
+        """Return the previous index modulo capacity."""
+        return (index - 1 + self._capacity) % self._capacity
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def enqueue(self, value: T) -> None:
+        """
+        Add *value* to the rear of the queue.
+
+        Parameters
+        ----------
+        value:
+            The element to enqueue.
+
+        Raises
+        ------
+        QueueFullError
+            If the queue is at capacity.
+        """
+        with self._lock:
+            if self._size == self._capacity:
+                raise QueueFullError(self._capacity)
+            self._enqueue_unsafe(value)
+
+    def dequeue(self) -> T:
+        """
+        Remove and return the front element.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("dequeue from an empty queue")
+            value = self._buffer[self._head]
+            self._buffer[self._head] = None
+            self._head = self._next_index(self._head)
+            self._size -= 1
+            return value  # type: ignore[return-value]
+
+    def front(self) -> T:
+        """
+        Return the front element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("front of an empty queue")
+            return self._buffer[self._head]  # type: ignore[return-value]
+
+    def rear(self) -> T:
+        """
+        Return the rear element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._size == 0:
+                raise EmptyStructureError("rear of an empty queue")
+            return self._buffer[self._prev_index(self._tail)]  # type: ignore[return-value]
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        """Return ``True`` if the queue contains no elements."""
+        return self._size == 0
+
+    def is_full(self) -> bool:
+        """Return ``True`` if the queue is at capacity."""
+        return self._size == self._capacity
+
+    def size(self) -> int:
+        """Return the number of elements in the queue."""
+        return self._size
+
+    def capacity(self) -> int:
+        """Return the maximum number of elements the queue can hold."""
+        return self._capacity
+
+    def clear(self) -> None:
+        """Remove all elements from the queue."""
+        with self._lock:
+            self._buffer = [None] * self._capacity
+            self._head = 0
+            self._tail = 0
+            self._size = 0
+
+    def copy(self) -> CircularQueue[T]:
+        """
+        Return a shallow copy of this queue.
+
+        Returns
+        -------
+        CircularQueue[T]
+        """
+        with self._lock:
+            new = CircularQueue[T](self._capacity)
+            new._buffer = list(self._buffer)
+            new._head = self._head
+            new._tail = self._tail
+            new._size = self._size
+            return new
+
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from front to rear.
+
+        Returns
+        -------
+        list[T]
+        """
+        with self._lock:
+            result: list[T] = []
+            idx = self._head
+            for _ in range(self._size):
+                val = self._buffer[idx]
+                if val is not None:
+                    result.append(val)
+                idx = self._next_index(idx)
+            return result
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    def __iter__(self) -> Iterator[T]:
+        with self._lock:
+            snapshot = self.to_list()
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        return self._size
+
+    def __bool__(self) -> bool:
+        return self._size > 0
+
+    def __repr__(self) -> str:
+        return f"CircularQueue(capacity={self._capacity}, items={self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, CircularQueue):
+            return NotImplemented
+        return self.to_list() == other.to_list()

pkstruct/linear/queues/linked_queue.py

@@ -0,0 +1,186 @@
+"""
+pkstruct.linear.queues.linked_queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A FIFO queue backed by a ``SinglyLinkedList``.
+
+``LinkedQueue`` composes the existing production-grade linked list.  Enqueue
+appends at the tail; dequeue removes from the head — both O(1).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TypeVar, cast
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.linked_lists.singly_linked_list import SinglyLinkedList
+from pkstruct.linear.queues.queue import Queue
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+
+class LinkedQueue(Queue[T]):
+    """
+    A thread-safe FIFO queue implemented on top of ``SinglyLinkedList``.
+
+    The internal list stores elements in order: front at the head, rear at
+    the tail.  ``enqueue`` appends (tail), ``dequeue`` removes from the head
+    — both O(1) amortised.
+
+    Parameters
+    ----------
+    items:
+        Optional iterable of initial values (front-to-rear order).
+        If omitted the queue starts empty.
+
+    Examples
+    --------
+    >>> q = LinkedQueue([1, 2, 3])
+    >>> q.enqueue(4)
+    >>> q.dequeue()
+    1
+    >>> q.front()
+    2
+    """
+
+    __slots__ = ("_list", "_lock")
+
+    def __init__(self, items: list[T] | None = None) -> None:
+        self._list: SinglyLinkedList[T] = SinglyLinkedList()
+        self._lock: StructureLock = StructureLock()
+        if items is not None:
+            for item in items:
+                self._list.insert(item)
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def enqueue(self, value: T) -> None:
+        """
+        Add *value* to the rear of the queue (tail of the list).
+
+        Parameters
+        ----------
+        value:
+            The element to enqueue.
+        """
+        with self._lock:
+            self._list.insert(value)
+
+    def dequeue(self) -> T:
+        """
+        Remove and return the front element (head of the list).
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("dequeue from an empty queue")
+            return cast(T, self._list.delete(position=0))
+
+    def front(self) -> T:
+        """
+        Return the front element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("front of an empty queue")
+            return self._list.get(0)
+
+    def rear(self) -> T:
+        """
+        Return the rear element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the queue is empty.
+        """
+        with self._lock:
+            if self._list.is_empty():
+                raise EmptyStructureError("rear of an empty queue")
+            return self._list.get(self._list.size() - 1)
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        """Return ``True`` if the queue contains no elements."""
+        return self._list.is_empty()
+
+    def size(self) -> int:
+        """Return the number of elements in the queue."""
+        return self._list.size()
+
+    def clear(self) -> None:
+        """Remove all elements from the queue."""
+        self._list.clear()
+
+    def copy(self) -> LinkedQueue[T]:
+        """
+        Return a shallow copy of this queue.
+
+        Returns
+        -------
+        LinkedQueue[T]
+        """
+        with self._lock:
+            new = LinkedQueue[T]()
+            new._list = cast(SinglyLinkedList[T], self._list.copy())
+            return new
+
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements, from front to rear.
+
+        Returns
+        -------
+        list[T]
+        """
+        return self._list.to_list()
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    def __iter__(self) -> Iterator[T]:
+        with self._lock:
+            snapshot = self.to_list()
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __bool__(self) -> bool:
+        return not self.is_empty()
+
+    def __repr__(self) -> str:
+        return f"LinkedQueue({self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, LinkedQueue):
+            return NotImplemented
+        return self.to_list() == other.to_list()

pkstruct/linear/queues/priority_queue.py

@@ -0,0 +1,202 @@
+"""
+pkstruct.linear.queues.priority_queue
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+A priority queue backed by a binary heap (``heapq``).
+
+``PriorityQueue`` wraps the standard library ``heapq`` module, adding thread
+safety and the full pkstruct queue interface.  The minimum element is always
+at the front.  Complexity is O(log n) for ``enqueue`` and ``dequeue``.
+"""
+
+from __future__ import annotations
+
+import heapq
+from collections.abc import Iterator
+from typing import TypeVar
+
+from pkstruct.linear.exceptions import EmptyStructureError
+from pkstruct.linear.queues.queue import Queue
+from pkstruct.shared.threading import StructureLock
+
+T = TypeVar("T")
+
+
+class PriorityQueue(Queue[T]):
+    """
+    A thread-safe min-heap priority queue.
+
+    The element with the smallest priority (or smallest value when no explicit
+    priority is given) is always at the front.  If two elements share the same
+    priority, the one enqueued first is served first (stable via insertion
+    counter).
+
+    Parameters
+    ----------
+    items:
+        Optional iterable of initial values.  All elements are heapified at
+        construction (O(n)).
+
+    Examples
+    --------
+    >>> pq = PriorityQueue([3, 1, 2])
+    >>> pq.dequeue()
+    1
+    >>> pq.enqueue(0)
+    >>> pq.dequeue()
+    0
+    """
+
+    __slots__ = ("_heap", "_lock", "_counter")
+
+    def __init__(self, items: list[T] | None = None) -> None:
+        self._heap: list[tuple[object, int, T]] = []
+        self._lock: StructureLock = StructureLock()
+        self._counter: int = 0
+        if items is not None:
+            for item in items:
+                self.enqueue(item)
+
+    # ------------------------------------------------------------------ #
+    #  Required operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def enqueue(self, value: T, priority: object = None) -> None:
+        """
+        Add *value* to the priority queue.
+
+        Parameters
+        ----------
+        value:
+            The element to enqueue.
+        priority:
+            Optional sort key.  If ``None``, *value* itself is used for
+            ordering (requires comparable elements).
+        """
+        with self._lock:
+            key: object = priority if priority is not None else value
+            heapq.heappush(self._heap, (key, self._counter, value))
+            self._counter += 1
+
+    def dequeue(self) -> T:
+        """
+        Remove and return the element with the smallest priority.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the priority queue is empty.
+        """
+        with self._lock:
+            if not self._heap:
+                raise EmptyStructureError("dequeue from an empty priority queue")
+            _, _, value = heapq.heappop(self._heap)
+            return value
+
+    def front(self) -> T:
+        """
+        Return the smallest-priority element without removing it.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the priority queue is empty.
+        """
+        with self._lock:
+            if not self._heap:
+                raise EmptyStructureError("front of an empty priority queue")
+            return self._heap[0][2]
+
+    def rear(self) -> T:
+        """
+        Return the largest-priority element without removing it.
+
+        This operation is O(n) because heap order does not directly expose
+        the maximum element.
+
+        Returns
+        -------
+        T
+
+        Raises
+        ------
+        EmptyStructureError
+            If the priority queue is empty.
+        """
+        with self._lock:
+            if not self._heap:
+                raise EmptyStructureError("rear of an empty priority queue")
+            return max(self._heap, key=lambda x: x[0])[2]  # type: ignore[arg-type, return-value]
+
+    # ------------------------------------------------------------------ #
+    #  Query operations                                                    #
+    # ------------------------------------------------------------------ #
+
+    def is_empty(self) -> bool:
+        """Return ``True`` if the priority queue contains no elements."""
+        return len(self._heap) == 0
+
+    def size(self) -> int:
+        """Return the number of elements in the priority queue."""
+        return len(self._heap)
+
+    def clear(self) -> None:
+        """Remove all elements from the priority queue."""
+        with self._lock:
+            self._heap.clear()
+            self._counter = 0
+
+    def copy(self) -> PriorityQueue[T]:
+        """
+        Return a shallow copy of this priority queue.
+
+        Returns
+        -------
+        PriorityQueue[T]
+        """
+        with self._lock:
+            new: PriorityQueue[T] = PriorityQueue()
+            new._heap = list(self._heap)
+            new._counter = self._counter
+            return new
+
+    def to_list(self) -> list[T]:
+        """
+        Return a list of all elements in priority order (smallest first).
+
+        Returns
+        -------
+        list[T]
+        """
+        with self._lock:
+            return [v for _, _, v in sorted(self._heap)]
+
+    # ------------------------------------------------------------------ #
+    #  Dunder methods                                                      #
+    # ------------------------------------------------------------------ #
+
+    def __iter__(self) -> Iterator[T]:
+        with self._lock:
+            snapshot = self.to_list()
+        return iter(snapshot)
+
+    def __len__(self) -> int:
+        return self.size()
+
+    def __bool__(self) -> bool:
+        return not self.is_empty()
+
+    def __repr__(self) -> str:
+        return f"PriorityQueue({self.to_list()!r})"
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, PriorityQueue):
+            return NotImplemented
+        return self.to_list() == other.to_list()