ringo-task-queue 0.1.0.dev6__py3-none-win_amd64.whl → 0.1.0.dev7__py3-none-win_amd64.whl

ringo_task_queue/concurrency.py

@@ -1,480 +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"]
+"""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"]