tigrbl_engine_memqueue 0.1.10.dev1__tar.gz

tigrbl_engine_memqueue-0.1.10.dev1/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.tox/
+.nox/
+.venv/
+.coverage
+htmlcov/
+build/
+dist/
+site/
+target/
+*.egg-info/
+*.pyc
+*.zip
+/.vendor
+/.tmp
+*.body
+.pip-cache/
+*.pyd
+.tmp-release-plan-check.json

tigrbl_engine_memqueue-0.1.10.dev1/PKG-INFO

@@ -0,0 +1,5 @@
+Metadata-Version: 2.4
+Name: tigrbl_engine_memqueue
+Version: 0.1.10.dev1
+Requires-Python: <3.14,>=3.10
+Requires-Dist: tigrbl

tigrbl_engine_memqueue-0.1.10.dev1/README.md

@@ -0,0 +1,23 @@
+# tigrbl_engine_memqueue
+
+This file is a package-local distribution entry point.
+It is not the authoritative location for repository governance, current target status, current state reporting, certification claims, or release evidence.
+
+## Canonical repository docs
+
+- `README.md`
+- `docs/README.md`
+- `docs/conformance/CURRENT_TARGET.md`
+- `docs/conformance/CURRENT_STATE.md`
+- `docs/conformance/NEXT_STEPS.md`
+- `docs/governance/DOC_POINTERS.md`
+- `docs/developer/PACKAGE_CATALOG.md`
+- `docs/developer/PACKAGE_LAYOUT.md`
+
+## Package identity
+
+- workspace path: `pkgs/engines/tigrbl_engine_memqueue`
+- workspace class: engine package
+- implementation layout: `src/tigrbl_engine_memqueue/`
+
+Long-form repository documentation is governed from `docs/`.

tigrbl_engine_memqueue-0.1.10.dev1/pyproject.toml

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling>=1.25.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tigrbl_engine_memqueue"
+version = "0.1.10.dev1"
+requires-python = ">=3.10,<3.14"
+dependencies = ["tigrbl"]
+
+[project.entry-points."tigrbl.engine"]
+memqueue = "tigrbl_engine_memqueue.plugin:register"
+
+[tool.uv.sources]
+tigrbl = { workspace = true }

tigrbl_engine_memqueue-0.1.10.dev1/src/tigrbl_engine_memqueue/__init__.py

@@ -0,0 +1,2 @@
+__all__ = ["__version__"]
+__version__ = "0.1.0"

tigrbl_engine_memqueue-0.1.10.dev1/src/tigrbl_engine_memqueue/plugin.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from tigrbl.engine.registry import register_engine
+
+from .queuehub import QueueHub
+from .session import QueueSession, AsyncQueueSession
+
+
+def register() -> None:
+    register_engine(kind="memqueue", build=build_memqueue, capabilities=capabilities)
+
+
+def capabilities() -> dict:
+    return {
+        "engine": "memqueue",
+        "transactional": False,
+        "async_native": True,
+        "persistence": "process",
+        "features": {"fifo", "lifo", "priority_optional", "named_queues"},
+    }
+
+
+def build_memqueue(*, mapping=None, spec=None, dsn=None, **_) -> tuple[object, object]:
+    mapping = dict(mapping or {})
+    async_ = bool(getattr(spec, "async_", False))
+
+    mode = str(mapping.get("mode", "fifo")).lower()
+    max_items = int(mapping.get("max_items", 100_000))
+    namespace = str(mapping.get("namespace", "default"))
+
+    engine = QueueHub(mode=mode, max_items=max_items, namespace=namespace)
+
+    if async_:
+        def sessionmaker():
+            return AsyncQueueSession(engine)
+    else:
+        def sessionmaker():
+            return QueueSession(engine)
+
+    return engine, sessionmaker

tigrbl_engine_memqueue-0.1.10.dev1/src/tigrbl_engine_memqueue/queuehub.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import heapq
+from collections import deque
+from dataclasses import dataclass
+from threading import Condition, RLock
+from time import monotonic
+from typing import Any
+
+
+@dataclass
+class _Q:
+    mode: str
+    max_items: int
+    lock: RLock
+    cv: Condition
+    # one of these is used depending on mode
+    dq: deque[Any] | None = None
+    heap: list[tuple[int, float, Any]] | None = None
+    seq: int = 0
+    closed: bool = False
+
+
+class QueueHub:
+    """Named in-process queues with blocking get/put.
+
+    Modes:
+      - fifo: deque append/pop left
+      - lifo: deque append/pop
+      - priority: heapq of (priority, t, item) (lower priority value first)
+    """
+
+    def __init__(self, *, mode: str = "fifo", max_items: int = 100_000, namespace: str = "default") -> None:
+        mode = (mode or "fifo").lower()
+        if mode not in {"fifo", "lifo", "priority"}:
+            raise ValueError("mode must be fifo|lifo|priority")
+        if max_items <= 0:
+            raise ValueError("max_items must be > 0")
+        self.mode = mode
+        self.max_items = int(max_items)
+        self.namespace = namespace
+        self._lock = RLock()
+        self._qs: dict[str, _Q] = {}
+
+    def _q(self, name: str) -> _Q:
+        k = name or "default"
+        with self._lock:
+            q = self._qs.get(k)
+            if q is None:
+                lock = RLock()
+                cv = Condition(lock)
+                if self.mode == "priority":
+                    q = _Q(mode=self.mode, max_items=self.max_items, lock=lock, cv=cv, heap=[])
+                else:
+                    q = _Q(mode=self.mode, max_items=self.max_items, lock=lock, cv=cv, dq=deque())
+                self._qs[k] = q
+            return q
+
+    def close(self, name: str = "default") -> None:
+        q = self._q(name)
+        with q.lock:
+            q.closed = True
+            q.cv.notify_all()
+
+    def put(self, name: str, item: Any, *, priority: int = 0, timeout: float | None = None) -> bool:
+        q = self._q(name)
+        deadline = None if timeout is None else (monotonic() + max(0.0, float(timeout)))
+        with q.lock:
+            while not q.closed and self.size(name) >= q.max_items:
+                if deadline is None:
+                    q.cv.wait()
+                else:
+                    remain = deadline - monotonic()
+                    if remain <= 0:
+                        return False
+                    q.cv.wait(remain)
+            if q.closed:
+                return False
+            if q.mode == "priority":
+                assert q.heap is not None
+                q.seq += 1
+                heapq.heappush(q.heap, (int(priority), monotonic(), item))
+            else:
+                assert q.dq is not None
+                q.dq.append(item)
+            q.cv.notify()
+            return True
+
+    def get(self, name: str, *, timeout: float | None = None) -> Any | None:
+        q = self._q(name)
+        deadline = None if timeout is None else (monotonic() + max(0.0, float(timeout)))
+        with q.lock:
+            while not q.closed and self.size(name) == 0:
+                if deadline is None:
+                    q.cv.wait()
+                else:
+                    remain = deadline - monotonic()
+                    if remain <= 0:
+                        return None
+                    q.cv.wait(remain)
+            if self.size(name) == 0:
+                return None
+            if q.mode == "priority":
+                assert q.heap is not None
+                _pri, _t, item = heapq.heappop(q.heap)
+            elif q.mode == "lifo":
+                assert q.dq is not None
+                item = q.dq.pop()
+            else:  # fifo
+                assert q.dq is not None
+                item = q.dq.popleft()
+            q.cv.notify()
+            return item
+
+    def drain(self, name: str, *, max_items: int | None = None) -> list[Any]:
+        q = self._q(name)
+        out: list[Any] = []
+        with q.lock:
+            n = self.size(name)
+            if max_items is not None:
+                n = min(n, int(max_items))
+            for _ in range(n):
+                item = self.get(name, timeout=0.0)
+                if item is None:
+                    break
+                out.append(item)
+            return out
+
+    def size(self, name: str) -> int:
+        q = self._q(name)
+        if q.mode == "priority":
+            assert q.heap is not None
+            return len(q.heap)
+        assert q.dq is not None
+        return len(q.dq)

tigrbl_engine_memqueue-0.1.10.dev1/src/tigrbl_engine_memqueue/session.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .queuehub import QueueHub
+
+
+class QueueSession:
+    def __init__(self, engine: QueueHub) -> None:
+        self._engine = engine
+        self._closed = False
+
+    def close(self) -> None:
+        self._closed = True
+
+    def put(self, item: Any, *, name: str = "default", priority: int = 0, timeout: float | None = None) -> bool:
+        self._require_open()
+        return self._engine.put(name, item, priority=priority, timeout=timeout)
+
+    def get(self, *, name: str = "default", timeout: float | None = None) -> Any | None:
+        self._require_open()
+        return self._engine.get(name, timeout=timeout)
+
+    def drain(self, *, name: str = "default", max_items: int | None = None) -> list[Any]:
+        self._require_open()
+        return self._engine.drain(name, max_items=max_items)
+
+    def qsize(self, *, name: str = "default") -> int:
+        self._require_open()
+        return self._engine.size(name)
+
+    def close_queue(self, *, name: str = "default") -> None:
+        self._require_open()
+        self._engine.close(name)
+
+    def _require_open(self) -> None:
+        if self._closed:
+            raise RuntimeError("session is closed")
+
+
+class AsyncQueueSession(QueueSession):
+    async def close(self) -> None:  # type: ignore[override]
+        super().close()