chunker and ui

core/chunker/queue.py

@@ -0,0 +1,76 @@
+"""
+ChunkQueue — bounded, thread-safe queue with sentinel-based shutdown.
+
+Demonstrates: Core data structures — queue.Queue (Interview Topic 5).
+"""
+
+import queue
+from typing import Optional
+
+from .models import Chunk
+
+# Sentinel value to signal workers to stop
+_SENTINEL = object()
+
+
+class ChunkQueue:
+    """
+    Thread-safe bounded queue for chunks.
+
+    Provides backpressure: producers block when the queue is full,
+    preventing unbounded memory usage.
+
+    Args:
+        maxsize: Maximum number of chunks in the queue (default: 10)
+    """
+
+    def __init__(self, maxsize: int = 10):
+        self._queue: queue.Queue = queue.Queue(maxsize=maxsize)
+        self._closed = False
+        self.maxsize = maxsize
+
+    def put(self, chunk: Chunk, timeout: Optional[float] = None) -> None:
+        """
+        Add a chunk to the queue. Blocks if full (backpressure).
+
+        Args:
+            chunk: The chunk to enqueue
+            timeout: Max seconds to wait (None = block forever)
+
+        Raises:
+            queue.Full: If timeout expires while queue is full
+        """
+        self._queue.put(chunk, timeout=timeout)
+
+    def get(self, timeout: Optional[float] = None) -> Optional[Chunk]:
+        """
+        Get next chunk from queue. Returns None if queue is closed.
+
+        Args:
+            timeout: Max seconds to wait (None = block forever)
+
+        Returns:
+            Chunk or None (if sentinel received, meaning queue is closed)
+
+        Raises:
+            queue.Empty: If timeout expires while queue is empty
+        """
+        item = self._queue.get(timeout=timeout)
+        if item is _SENTINEL:
+            # Re-put sentinel so other workers also see it
+            self._queue.put(_SENTINEL)
+            return None
+        return item
+
+    def close(self) -> None:
+        """Signal all consumers to stop by inserting a sentinel."""
+        self._closed = True
+        self._queue.put(_SENTINEL)
+
+    @property
+    def is_closed(self) -> bool:
+        return self._closed
+
+    def qsize(self) -> int:
+        """Current number of items in the queue (approximate)."""
+        return self._queue.qsize()