ringo-task-queue 0.1.0.dev2__py3-none-win_amd64.whl → 0.1.0.dev4__py3-none-win_amd64.whl

ringo_task_queue/_version.py

@@ -1,8 +1,8 @@
 """Release-line constants shared by runtime packaging checks."""
 
-SDK_VERSION = "0.1.0.dev2"
+SDK_VERSION = "0.1.0.dev4"
 PROTOCOL_MAJOR = 1
-PROTOCOL_MINOR = 1
+PROTOCOL_MINOR = 2
 SCHEMA_VERSION = 3
 
 
@@ -11,5 +11,7 @@ def daemon_version_for_sdk(version: str = SDK_VERSION) -> str:
     if ".dev" in version:
         base, _, suffix = version.rpartition(".dev")
         if suffix.isdigit():
-            return f"{base}-dev"
+            # Keep the historical dev0 daemon spelling while preserving the
+            # release-candidate sequence used by later development wheels.
+            return f"{base}-dev" if suffix == "0" else f"{base}-dev.{suffix}"
     return version

ringo_task_queue/bin/manifest.json

@@ -4,17 +4,17 @@
       "arch": "amd64",
       "filename": "ringo-task-queue-windows-amd64.exe",
       "os": "windows",
-      "sha256": "ad38397d8fe70fb4712f43b32d336e6ebb8550a552c9ab376da5f3785686571a",
-      "size": 22874624
+      "sha256": "4f2d5becfea37472adeabe344065ddba6ba588b7ae42d73b4f014c2f81d80bd1",
+      "size": 22876672
     }
   ],
-  "buildCommit": "38c81fd",
+  "buildCommit": "53352c1",
   "buildDate": "2026-03-01T00:00:00Z",
   "manifestVersion": 1,
   "name": "ringo-task-queue",
   "protocolMajor": 1,
-  "protocolMinor": 1,
-  "releaseManifestSha256": "23e6bb426c34fa417ca0921acfb9d57bbd726616f597894b40cef224fd469eb5",
+  "protocolMinor": 2,
+  "releaseManifestSha256": "adc378b540af4e47dc4a882889679e00be2e225f49cc6de5bea687388d49d482",
   "schemaVersion": 3,
-  "version": "0.1.0-dev.2"
+  "version": "0.1.0-dev.4"
 }

ringo_task_queue/client.py

@@ -14,6 +14,7 @@ from grpc_health.v1 import health_pb2, health_pb2_grpc
 from . import _pb
 from ._proto.ringo.v1 import queue_pb2, queue_pb2_grpc
 from ._version import PROTOCOL_MAJOR, PROTOCOL_MINOR, SDK_VERSION
+from .concurrency import AdaptiveConcurrency, ResourceConcurrency
 from .errors import (
     IncompatibleVersionError,
     InvalidArgumentError,
@@ -789,7 +790,8 @@ class TaskQueue:
         handler: Handler,
         *,
         task_types: Iterable[str] | None = None,
-        concurrency: int = 1,
+        concurrency: int | ResourceConcurrency | AdaptiveConcurrency = 1,
+        weight: int = 1,
         lease_duration: timedelta = timedelta(seconds=60),
         grace_period: timedelta = timedelta(seconds=30),
         on_idle: Callable[[], Any] | None = None,
@@ -818,8 +820,18 @@ class TaskQueue:
             raise InvalidArgumentError("handler must be callable")
         if on_idle is not None and not callable(on_idle):
             raise InvalidArgumentError("on_idle must be callable")
-        if concurrency < 1 or concurrency > 2**32 - 1:
-            raise InvalidArgumentError("concurrency must fit in a non-zero uint32")
+        if isinstance(concurrency, bool) or not isinstance(
+            concurrency, (int, ResourceConcurrency, AdaptiveConcurrency)
+        ):
+            raise InvalidArgumentError(
+                "concurrency must be an integer, ResourceConcurrency, or AdaptiveConcurrency"
+            )
+        if isinstance(concurrency, int) and (concurrency < 1 or concurrency > 2**31 - 1):
+            raise InvalidArgumentError(
+                "initial fixed concurrency must be between 1 and 2**31-1"
+            )
+        if isinstance(weight, bool) or not isinstance(weight, int) or weight < 1:
+            raise InvalidArgumentError("weight must be a positive integer")
         if lease_duration < timedelta(0):
             raise InvalidArgumentError("lease_duration must not be negative")
         if grace_period < timedelta(0):
@@ -832,6 +844,7 @@ class TaskQueue:
             lease_duration=lease_duration,
             grace_period=grace_period,
             on_idle=on_idle,
+            weight=weight,
         )
         self._client._register_worker(worker)
         return worker

ringo_task_queue/concurrency.py

@@ -0,0 +1,480 @@
+"""Process-local dynamic Worker concurrency controllers.
+
+Controllers are deliberately small asyncio-local admission pools.  A Worker
+holds at most one speculative (probe) credit; consuming it turns the credit
+into a running permit and immediately lets the controller grant another
+member.  The controller never cancels a running handler.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from .errors import UnavailableError
+
+if TYPE_CHECKING:  # pragma: no cover
+    from .worker import Worker
+
+_MAX_CAPACITY = 2**31 - 1
+_PROBE_SECONDS = 0.25
+
+
+@dataclass
+class _Member:
+    worker: "Worker"
+    weight: int
+    deficit: int = 0
+    probe: bool = False
+    revoking: bool = False
+    active: bool = False
+    cooldown_until: float = 0.0
+    running: int = 0
+    attached: bool = True
+    session_ready: bool = False
+    probe_generation: int = 0
+
+
+class ResourceConcurrency:
+    """A shareable, process-local resource capacity pool.
+
+    ``capacity`` is the total number of admission permits, not a per-worker
+    quota.  The same object may be supplied to workers on different queues or
+    clients in one event loop.  Capacity changes are serialized and are
+    non-preemptive: existing handlers continue to hold their permits.
+    """
+
+    def __init__(self, capacity: int) -> None:
+        self._validate_capacity(capacity)
+        self._capacity = capacity
+        self._members: list[_Member] = []
+        self._lock = asyncio.Lock()
+        # Capacity transitions stay linearizable across the network wait used
+        # to withdraw outstanding probe credits.
+        self._resize_lock = asyncio.Lock()
+        self._cursor = 0
+        self._closed = False
+        self._grant_paused = False
+        self._resize_needs_retry = False
+        self._loop: asyncio.AbstractEventLoop | None = None
+
+    @staticmethod
+    def _validate_capacity(value: int) -> None:
+        if isinstance(value, bool) or not isinstance(value, int):
+            raise ValueError("capacity must be an integer")
+        if value < 0 or value > _MAX_CAPACITY:
+            raise ValueError(f"capacity must be between 0 and {_MAX_CAPACITY}")
+
+    @property
+    def capacity(self) -> int:
+        return self._capacity
+
+    @property
+    def members(self) -> int:
+        """Number of currently attached workers (primarily for diagnostics)."""
+        return sum(1 for member in self._members if member.attached)
+
+    async def set_capacity(self, capacity: int) -> None:
+        """Publish a new capacity and await withdrawal of idle probes."""
+        self._validate_capacity(capacity)
+        self._check_loop()
+        async with self._resize_lock:
+            async with self._lock:
+                probes = self._prepare_resize_locked(capacity)
+            await self._finish_resize(capacity, probes)
+
+    def _prepare_resize_locked(self, capacity: int) -> list[_Member]:
+        if self._closed:
+            raise RuntimeError("concurrency controller is closed")
+        old = self._capacity
+        self._capacity = capacity
+        probes: list[_Member] = []
+        if capacity != old or self._resize_needs_retry:
+            # Pause every grant while all live streams receive the new target.
+            # Existing probes are withdrawn and then re-granted under that
+            # target; assignment-before-result still promotes the reservation.
+            self._grant_paused = True
+            probes = [
+                member
+                for member in self._members
+                if member.attached and member.probe
+            ]
+            for member in probes:
+                if not member.revoking:
+                    member.revoking = True
+                    member.probe_generation += 1
+        return probes
+
+    async def _finish_resize(self, capacity: int, probes: list[_Member]) -> None:
+        async with self._lock:
+            if not self._grant_paused:
+                await self._grant_locked()
+                return
+            probe_ids = {id(member) for member in probes}
+            actions = [
+                (member, id(member) in probe_ids)
+                for member in self._members
+                if member.attached and member.session_ready
+            ]
+        results = await asyncio.gather(
+            *(
+                member.worker._withdraw_controller_probe(member, capacity)
+                if has_probe
+                else member.worker._publish_controller_target(capacity)
+                for member, has_probe in actions
+            ),
+            return_exceptions=True,
+        )
+        failed = False
+        async with self._lock:
+            for (member, has_probe), result in zip(actions, results):
+                if result is not True:
+                    failed = True
+                elif has_probe and member.probe and member.revoking:
+                    member.probe = False
+                    member.revoking = False
+            self._resize_needs_retry = failed
+            self._grant_paused = failed
+            if not failed:
+                await self._grant_locked()
+        if failed:
+            raise UnavailableError(
+                "concurrency capacity changed locally, but an old Work probe "
+                "or target snapshot could not be published; retry after the "
+                "stream reconnects"
+            )
+
+    async def close(self) -> None:
+        """Stop future grants and withdraw attached idle probes."""
+        self._check_loop()
+        async with self._resize_lock:
+            async with self._lock:
+                self._closed = True
+                self._grant_paused = True
+                probes = [member for member in self._members if member.probe]
+                for member in probes:
+                    member.revoking = True
+                    member.probe_generation += 1
+            results: list[object] = []
+            if probes:
+                results = await asyncio.gather(
+                    *(
+                        member.worker._withdraw_controller_probe(
+                            member, 0, force_target=True
+                        )
+                        for member in probes
+                    ),
+                    return_exceptions=True,
+                )
+            async with self._lock:
+                for member, result in zip(probes, results):
+                    if result is True and member.probe and member.revoking:
+                        member.probe = False
+                        member.revoking = False
+
+    # The following methods are Worker integration points.  They are kept
+    # private so a controller cannot be confused with a transport-level quota.
+    def _check_loop(self) -> None:
+        loop = asyncio.get_running_loop()
+        if self._loop is None:
+            self._loop = loop
+        elif self._loop is not loop:
+            raise RuntimeError("a concurrency controller cannot cross event loops")
+
+    def _attach(self, worker: "Worker", weight: int) -> _Member:
+        if self._closed:
+            raise RuntimeError("concurrency controller is closed")
+        if isinstance(weight, bool) or not isinstance(weight, int) or weight < 1:
+            raise ValueError("weight must be a positive integer")
+        for member in self._members:
+            if member.worker is worker:
+                return member
+        member = _Member(worker=worker, weight=weight)
+        self._members.append(member)
+        return member
+
+    async def _start_member(self, member: _Member | None) -> None:
+        if member is None:
+            return
+        self._check_loop()
+        # Session admission and capacity transitions share the complete resize
+        # lane, including the initial WorkResult wait.  A stale initial target
+        # therefore cannot land after a completed resize.
+        async with self._resize_lock:
+            await member.worker._publish_controller_initial(self._capacity)
+            async with self._lock:
+                if member.attached and not self._closed:
+                    member.session_ready = True
+                    await self._grant_locked()
+
+    async def _detach(self, member: _Member) -> None:
+        self._check_loop()
+        async with self._resize_lock:
+            async with self._lock:
+                if not member.attached:
+                    return
+                member.attached = False
+                member.session_ready = False
+                needs_withdraw = member.probe and not member.revoking
+                if needs_withdraw:
+                    member.revoking = True
+                    member.probe_generation += 1
+            withdrawn = True
+            if needs_withdraw:
+                withdrawn = await member.worker._withdraw_controller_probe(
+                    member, 0, force_target=True
+                )
+            async with self._lock:
+                if withdrawn is True and member.probe and member.revoking:
+                    member.probe = False
+                    member.revoking = False
+                await self._grant_locked()
+                self._prune_detached()
+
+    def _prune_detached(self) -> None:
+        self._members[:] = [
+            member
+            for member in self._members
+            if member.attached or member.running or member.probe
+        ]
+        if self._members:
+            self._cursor %= len(self._members)
+        else:
+            self._cursor = 0
+
+    async def _stream_lost(self, member: _Member | None) -> None:
+        """Return a probe whose old Work stream disappeared.
+
+        The server-side credit vanished with that stream.  Running permits are
+        deliberately untouched; only the unused probe is made available for
+        republication after the replacement session registers.
+        """
+        if member is None:
+            return
+        self._check_loop()
+        async with self._lock:
+            member.session_ready = False
+            if member.probe:
+                member.probe = False
+                member.revoking = False
+                member.probe_generation += 1
+            await self._grant_locked()
+
+    async def _probe_consumed(self, member: _Member) -> bool:
+        self._check_loop()
+        async with self._lock:
+            if not member.probe:
+                return False
+            # This also handles assignment-before-revoke-result: the probe is
+            # promoted to running and the in-flight withdrawal must not release
+            # the resulting permit.
+            member.probe = False
+            member.revoking = False
+            member.active = True
+            member.running += 1
+            await self._grant_locked()
+            return True
+
+    async def _release_running(
+        self,
+        member: _Member,
+        *,
+        success: bool = False,
+        congestion: bool = False,
+    ) -> None:
+        self._check_loop()
+        # Automatic AIMD transitions and manual set_capacity calls share one
+        # end-to-end resize lane, including the correlated withdrawal wait.
+        async with self._resize_lock:
+            resize_capacity: int | None = None
+            probes: list[_Member] = []
+            async with self._lock:
+                controller = self
+                saturated = self._admission_count() >= self._capacity
+                if member.running:
+                    member.running -= 1
+                if self._closed:
+                    self._prune_detached()
+                    return
+                if isinstance(controller, AdaptiveConcurrency):
+                    if success and saturated and self._capacity > 0:
+                        controller._successes += 1
+                        controller._successes = min(
+                            controller._successes, self._capacity
+                        )
+                        if controller._successes >= self._capacity:
+                            controller._successes = 0
+                            new_capacity = min(
+                                _MAX_CAPACITY,
+                                controller._capacity + 1,
+                                controller.maximum,
+                            )
+                            if new_capacity != controller._capacity:
+                                resize_capacity = new_capacity
+                                probes = self._prepare_resize_locked(new_capacity)
+                    elif congestion:
+                        controller._successes = 0
+                        resize_capacity = max(
+                            controller.minimum,
+                            int(controller._capacity * controller.mult_decrease),
+                        )
+                        if resize_capacity < controller._capacity:
+                            # Stop grants and reserve every probe before releasing
+                            # the lock; withdrawal itself happens outside it.
+                            probes = self._prepare_resize_locked(resize_capacity)
+                if resize_capacity is None:
+                    await self._grant_locked()
+                self._prune_detached()
+            if resize_capacity is not None:
+                await self._finish_resize(resize_capacity, probes)
+
+    def _admission_count(self) -> int:
+        return sum(member.running + int(member.probe) for member in self._members)
+
+    def _choose_member(self) -> _Member | None:
+        """Choose with smooth weighted round-robin admission.
+
+        Members whose probes have expired enter a short cooldown before the
+        same weighted rotation can issue a bounded discovery probe again.  A
+        continuously consuming member therefore remains work-conserving while
+        an idle member is never permanently starved.
+        """
+        now = asyncio.get_running_loop().time()
+        eligible = [
+            member
+            for member in self._members
+            if member.attached
+            and member.session_ready
+            and not member.probe
+            and (member.active or now >= member.cooldown_until)
+        ]
+        if not eligible:
+            return None
+        total = sum(member.weight for member in eligible)
+        count = len(self._members)
+        ordered = [
+            self._members[(self._cursor + i) % count]
+            for i in range(count)
+            if self._members[(self._cursor + i) % count] in eligible
+        ]
+        for member in eligible:
+            member.deficit += member.weight
+        best = max(ordered, key=lambda member: member.deficit)
+        best.deficit -= total
+        self._cursor = (self._members.index(best) + 1) % count
+        return best
+
+    async def _grant_locked(self) -> None:
+        if self._closed or self._grant_paused:
+            return
+        while self._admission_count() < self._capacity:
+            member = self._choose_member()
+            if member is None:
+                return
+            member.probe = True
+            member.probe_generation += 1
+            generation = member.probe_generation
+            asyncio.create_task(
+                self._publish_probe(member, generation),
+                name=f"ringo-concurrency-probe-{member.worker.worker_id}",
+            )
+
+    async def _publish_probe(self, member: _Member, generation: int) -> None:
+        try:
+            await member.worker._publish_controller_probe(
+                member, self._capacity, generation
+            )
+            # An unused probe is a temporary admission reservation only.  It
+            # must be withdrawn even when the server has no task for a member.
+            asyncio.create_task(
+                self._expire_probe(member, generation),
+                name=f"ringo-probe-expiry-{member.worker.worker_id}",
+            )
+        except Exception:
+            async with self._lock:
+                if member.probe and member.probe_generation == generation:
+                    member.probe = False
+                    member.active = False
+                    member.cooldown_until = (
+                        asyncio.get_running_loop().time() + _PROBE_SECONDS
+                    )
+                    asyncio.create_task(
+                        self._wake_member(member),
+                        name=f"ringo-probe-failure-{member.worker.worker_id}",
+                    )
+                    await self._grant_locked()
+
+    async def _expire_probe(self, member: _Member, generation: int) -> None:
+        await asyncio.sleep(_PROBE_SECONDS)
+        async with self._lock:
+            if (
+                self._closed
+                or not member.probe
+                or member.revoking
+                or member.probe_generation != generation
+            ):
+                return
+            member.revoking = True
+            member.active = False
+            member.probe_generation += 1
+            capacity = self._capacity
+        withdrawn = await member.worker._withdraw_controller_probe(member, capacity)
+        async with self._lock:
+            if withdrawn is True and member.probe and member.revoking:
+                member.probe = False
+                member.revoking = False
+                member.cooldown_until = (
+                    asyncio.get_running_loop().time() + _PROBE_SECONDS
+                )
+                asyncio.create_task(
+                    self._wake_member(member),
+                    name=f"ringo-probe-cooldown-{member.worker.worker_id}",
+                )
+            await self._grant_locked()
+
+    async def _wake_member(self, member: _Member) -> None:
+        delay = max(0.0, member.cooldown_until - asyncio.get_running_loop().time())
+        if delay:
+            await asyncio.sleep(delay)
+        async with self._lock:
+            if member.attached and not member.probe and not self._closed:
+                await self._grant_locked()
+
+
+class AdaptiveConcurrency(ResourceConcurrency):
+    """AIMD resource controller (additive increase, multiplicative decrease)."""
+
+    def __init__(
+        self,
+        initial: int,
+        *,
+        minimum: int = 1,
+        maximum: int = _MAX_CAPACITY,
+    ) -> None:
+        self._validate_capacity(minimum)
+        self._validate_capacity(maximum)
+        self._validate_capacity(initial)
+        if minimum > maximum:
+            raise ValueError("minimum must not exceed maximum")
+        if not minimum <= initial <= maximum:
+            raise ValueError("initial must be between minimum and maximum")
+        super().__init__(initial)
+        self.minimum = minimum
+        self.maximum = maximum
+        self.mult_decrease = 0.5
+        self._successes = 0
+
+    async def set_capacity(self, capacity: int) -> None:
+        self._validate_capacity(capacity)
+        if not self.minimum <= capacity <= self.maximum:
+            raise ValueError("capacity must be between minimum and maximum")
+        self._check_loop()
+        async with self._resize_lock:
+            async with self._lock:
+                self._successes = 0
+                probes = self._prepare_resize_locked(capacity)
+            await self._finish_resize(capacity, probes)
+
+
+__all__ = ["AdaptiveConcurrency", "ResourceConcurrency"]

ringo_task_queue/errors.py

@@ -143,9 +143,16 @@ def map_rpc_error(exc: grpc.aio.AioRpcError) -> RingoError:
 class RetryTaskError(Exception):
     """Raise from a handler to retry with an optional per-attempt delay."""
 
-    def __init__(self, message: str = "", *, delay: float | None = None) -> None:
+    def __init__(
+        self,
+        message: str = "",
+        *,
+        delay: float | None = None,
+        congestion: bool = False,
+    ) -> None:
         super().__init__(message)
         self.delay = delay
+        self.congestion = congestion
 
 
 class PermanentTaskError(Exception):