Method acquire

contrib/multilingual/api_pool.py:165–237

Acquire a slot on the least-loaded available key. Scheduling priority: 1. **Recovered keys** — rate-limited keys whose backoff has expired become available again. 2. **Least-loaded key** — among available keys, pick the one with the fewest ``active_req

(self, timeout: float | None = None)

    # -- Public API -----------------------------------------------------------

    def acquire(self, timeout: float | None = None) -> ApiKey:
        """Acquire a slot on the least-loaded available key.

        Scheduling priority:

        1. **Recovered keys** — rate-limited keys whose backoff has expired
           become available again.
        2. **Least-loaded key** — among available keys, pick the one with
           the fewest ``active_requests``.
        3. **Block** — if every non-rate-limited key is at capacity, wait
           for a slot to free up or a rate-limited key to recover.

        Parameters
        ----------
        timeout :
            Maximum seconds to wait.  ``None`` means wait indefinitely.

        Returns
        -------
        ApiKey
            A key with at least one available slot.

        Raises
        ------
        RuntimeError
            If *timeout* expires before a slot becomes available.
        """
        deadline = time.monotonic() + timeout if timeout is not None else None

        with self._condition:
            while True:
                now = time.monotonic()

                # Step 1: recover rate-limited keys whose backoff has expired
                self._recover_expired_keys(now)

                # Step 2: find available keys (not rate-limited, slots open)
                available = [k for k in self._keys if k.available]
                if available:
                    key = min(available, key=lambda k: k.active_requests)
                    key.active_requests += 1
                    key.total_requests += 1
                    self._total_requests_served += 1
                    _now_active = sum(k.active_requests for k in self._keys)
                    if _now_active > self._peak_active_requests:
                        self._peak_active_requests = _now_active
                    logger.debug(
                        "Pool: slot on key …%s (%d/%d active)",
                        key.key[-8:],
                        key.active_requests,
                        key.max_concurrent,
                    )
                    return key

                # Step 3: no capacity — compute wait time
                wait_for = self._next_available_in(now)
                remaining = self._remaining_timeout(deadline)
                if remaining is not None and remaining <= 0: