robotframework-parallelrunner 0.3.1__tar.gz → 0.4.0__tar.gz

{robotframework_parallelrunner-0.3.1 → robotframework_parallelrunner-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: robotframework-parallelrunner
-Version: 0.3.1
+Version: 0.4.0
 Summary: Run a keyword in parallel inside a single Robot Framework test case, with one clean, ordered log.html.
 License-Expression: MIT
 License-File: LICENSE
@@ -230,11 +230,11 @@ Things to keep in mind:
   made thread-safe for you; your own keyword's side effects are not. If it
   writes to a shared variable, file, or object without a lock, running it
   concurrently can race the same way any multi-threaded code can.
-- **You need per-item retries or a per-item timeout.** Not implemented yet
-  (see [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)). A Robot `[Timeout]` on the test or keyword does
-  interrupt the whole batch when it expires and replays the logs collected so
-  far, but calls that are already running can't be stopped: they keep running
-  in the background until they return.
+- **You need per-item retries.** Not implemented yet (see
+  [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)). A per-call limit is: `call_timeout=10s` fails
+  only the call that hangs and lets the others finish. Note that a timed-out
+  call can't be killed - it keeps running in the background unless the
+  keyword declares `_cancelled` and stops when it is set.
 - **You need process-level isolation** (a crash in one call shouldn't be
   able to affect another) or cross-machine parallelism — that's pabot's
   domain, not this library's.

{robotframework_parallelrunner-0.3.1 → robotframework_parallelrunner-0.4.0}/README.md

@@ -196,11 +196,11 @@ Things to keep in mind:
   made thread-safe for you; your own keyword's side effects are not. If it
   writes to a shared variable, file, or object without a lock, running it
   concurrently can race the same way any multi-threaded code can.
-- **You need per-item retries or a per-item timeout.** Not implemented yet
-  (see [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)). A Robot `[Timeout]` on the test or keyword does
-  interrupt the whole batch when it expires and replays the logs collected so
-  far, but calls that are already running can't be stopped: they keep running
-  in the background until they return.
+- **You need per-item retries.** Not implemented yet (see
+  [ROADMAP.md](https://github.com/cristiangarciavd/robotframework-parallelrunner/blob/main/ROADMAP.md)). A per-call limit is: `call_timeout=10s` fails
+  only the call that hangs and lets the others finish. Note that a timed-out
+  call can't be killed - it keeps running in the background unless the
+  keyword declares `_cancelled` and stops when it is set.
 - **You need process-level isolation** (a crash in one call shouldn't be
   able to affect another) or cross-machine parallelism — that's pabot's
   domain, not this library's.

{robotframework_parallelrunner-0.3.1 → robotframework_parallelrunner-0.4.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "poetry.core.masonry.api"
 name = "robotframework-parallelrunner"
 # Single source of truth for the version: bump with `poetry version patch|minor|major`.
 # ParallelRunner.__version__ / ROBOT_LIBRARY_VERSION read it back from the installed metadata.
-version = "0.3.1"
+version = "0.4.0"
 description = "Run a keyword in parallel inside a single Robot Framework test case, with one clean, ordered log.html."
 readme = "README.md"
 license = "MIT"

{robotframework_parallelrunner-0.3.1 → robotframework_parallelrunner-0.4.0}/src/ParallelRunner/__init__.py

@@ -13,7 +13,7 @@ Keyword documentation:
 https://cristiangarciavd.github.io/robotframework-parallelrunner/ParallelRunner.html
 """
 
-from .parallel_library import ParallelLibrary, ParallelRunner, ParallelTaskError
+from .parallel_library import ParallelLibrary, ParallelRunner, ParallelTaskError, log_to_robot
 from .version import __version__
 
-__all__ = ["ParallelRunner", "ParallelLibrary", "ParallelTaskError", "__version__"]
+__all__ = ["ParallelRunner", "ParallelLibrary", "ParallelTaskError", "log_to_robot", "__version__"]

{robotframework_parallelrunner-0.3.1 → robotframework_parallelrunner-0.4.0}/src/ParallelRunner/parallel_library.py

@@ -1,15 +1,19 @@
 import os
 import importlib
+import inspect
 import queue
 import threading
 import time
 from typing import Iterable, Any, List, Dict, Optional, Tuple, Union
 from robot.api import logger
+from robot.errors import DataError
 try:
     from robot.errors import TimeoutExceeded
 except ImportError:  # Robot Framework < 7.0
     from robot.errors import TimeoutError as TimeoutExceeded
 from robot.libraries.BuiltIn import BuiltIn
+from robot.running.arguments import PythonArgumentParser
+from robot.utils import secs_to_timestr, timestr_to_secs
 
 from .version import __version__
 
@@ -35,6 +39,47 @@ def _normalize_level(level: Any) -> Optional[str]:
     return name if name in LOG_LEVELS or name == "IGNORE" else None
 
 
+def _normalize_name(name: str) -> str:
+    """Keyword name comparison the way Robot does it: ignoring case, spaces and underscores."""
+    return name.lower().replace(" ", "").replace("_", "")
+
+
+def _not_given(value: Any) -> bool:
+    """None, an empty string or "None" (any case - Robot's usual spelling of None)."""
+    return value is None or (isinstance(value, str) and value.strip().upper() in ("", "NONE"))
+
+
+# Who owns the result of a call that may time out: the worker that ran it, or
+# the main thread that timed it out. See `ParallelRunner._run_in_threads`.
+_WORKER, _MAIN = "worker", "main"
+_NOT_SET = object()
+
+
+def log_to_robot(msg: Any, level: str = "INFO") -> None:
+    """Logs ``msg`` straight to Robot Framework, accepting the same levels as
+    the ``_logger`` that `Run Parallel Scenarios` injects.
+
+    Use it as the fallback when a parallel-ready keyword is called directly
+    (without `Run Parallel Scenarios`)::
+
+        from ParallelRunner import log_to_robot
+
+        def verify_agent(self, agent_id, _logger=None):
+            log = _logger or log_to_robot
+            log("details", "DEBUG")
+
+    Unlike ``robot.api.logger.write``, it accepts ``IGNORE`` (dropped), any
+    case and Python ``logging`` names (``WARNING``), and logs a message with an
+    unknown level at INFO, prefixed with the level, instead of failing.
+    """
+    name = _normalize_level(level)
+    if name == "IGNORE":
+        return
+    if name is None:
+        name, msg = "INFO", f"[{level}] {msg}"
+    logger.write(msg, name)
+
+
 class ParallelTaskError(RuntimeError):
     """
     Raised when at least one parallel task failed: by ``run_parallel_scenarios``
@@ -93,18 +138,33 @@ class ParallelRunner:
     index) as its first argument and an injected ``_logger`` callable that
     it should use instead of ``robot.api.logger``:
 
-    | from robot.api import logger
+    | from ParallelRunner import log_to_robot
     |
     | class MyLibrary:
-    |     def verify_agent(self, agent_id, _logger=None, **kwargs):
-    |         log = _logger or (lambda msg, level="INFO": logger.write(msg, level))
+    |     def verify_agent(self, agent_id: int, timeout: float = 10, _logger=None, **kwargs):
+    |         log = _logger or log_to_robot
     |         log(f"Checking agent {agent_id}")
     |         ...
     |         return result
 
     ``_logger(msg, level)`` accepts every Robot Framework log level (see
-    `Log levels`) plus ``IGNORE`` (dropped). Any extra named argument given to
-    `Run Parallel Scenarios` is forwarded to every call as ``**kwargs``.
+    `Log levels`) plus ``IGNORE`` (dropped). ``log_to_robot`` is the fallback
+    for when the keyword is called directly: it accepts the same levels
+    (``robot.api.logger.write`` fails on ``IGNORE`` or ``WARNING``).
+
+    Any extra named argument given to `Run Parallel Scenarios` is forwarded
+    to every call as ``**kwargs``. Arguments are converted by the method's
+    type hints (and default values) exactly as when the keyword is called
+    directly: ``timeout=5`` arrives as the number ``5.0`` above. Items that
+    are strings are converted the same way; other items (numbers, lists,
+    dictionaries from a variable) are passed as they are.
+
+    The keyword is found by its method name (``Verify Agent`` ->
+    ``verify_agent``) or by a custom name given with ``@keyword("...")``,
+    ignoring case, spaces and underscores, like Robot does.
+
+    To be stoppable when it times out, the method can also declare a
+    ``_cancelled`` parameter: see `Call timeouts and cancellation`.
 
     Logging is made thread-safe for you; your keyword's own side effects are
     not. Protect shared state (files, shared objects) with a lock.
@@ -118,7 +178,7 @@ class ParallelRunner:
     | item     | The item (or repeat index) the call received. |
     | logs     | List of ``(level, message)`` tuples captured during the call. |
     | result   | The return value of the call (only when ``status`` is ``PASS``). |
-    | error    | The error message (only when ``status`` is ``FAIL``). |
+    | error    | The error message (only when ``status`` is ``FAIL``), e.g. ``Timed out after 10 seconds`` with ``call_timeout``. |
 
     = Failures =
 
@@ -168,10 +228,48 @@ class ParallelRunner:
 
     Python threads can't be killed, so calls that are already running keep
     running in the background until they return (possibly while the next test
-    runs); calls that had not started yet are not started. The worker threads
-    are daemon threads, so they never keep the Robot process alive after the
-    run. A keyword that may hang (e.g. network I/O) should set its own
-    timeouts (e.g. ``requests.get(url, timeout=10)``).
+    runs) - unless they cooperate, see `Call timeouts and cancellation`.
+    Calls that had not started yet are not started. The worker threads are
+    daemon threads, so they never keep the Robot process alive after the run.
+    A keyword that may hang (e.g. network I/O) should set its own timeouts
+    (e.g. ``requests.get(url, timeout=10)``).
+
+    A Robot timeout fails the whole test and can't be handled with
+    `Run Keyword And Ignore Error`. To fail only the call that hangs, use
+    ``call_timeout``.
+
+    = Call timeouts and cancellation =
+
+    ``call_timeout`` limits how long *each call* may run, e.g.
+    ``call_timeout=10s`` (Robot's time format). A call still running after
+    that becomes a failed call - error ``Timed out after 10 seconds``, with its
+    partial logs - while the other calls keep running and finish normally. It
+    is then reported like any other failed call: `Run Parallel Scenarios`
+    fails with ``ParallelTaskError`` (which, unlike a Robot timeout, can be
+    handled), or returns it with ``status`` ``FAIL`` when
+    ``fail_on_error=False``.
+
+    | ${results}= | Run Parallel Scenarios | keyword=Verify Agent | library=MyLibrary | for_loop_iterable=${agents} | call_timeout=10s | fail_on_error=False |
+
+    The timed-out call can't be killed either: it keeps running in the
+    background, and a new worker thread takes its place so the remaining
+    calls still run ``ROBOT_THREAD_WORKERS`` at a time.
+
+    A keyword that can stop early declares a ``_cancelled`` parameter.
+    `Run Parallel Scenarios` then passes it a ``threading.Event`` that is set
+    when that call times out, or when a Robot ``[Timeout]`` interrupts the
+    batch. The keyword checks it between steps, or waits on it instead of
+    sleeping:
+
+    | def poll_job(self, job_id, _logger=None, _cancelled=None):
+    |     while not job_done(job_id):
+    |         if _cancelled is not None and _cancelled.wait(1):   # sleeps 1 s, wakes up if cancelled
+    |             _logger(f"Stopped waiting for {job_id}", "WARN")
+    |             return None
+
+    ``_cancelled`` is only passed to methods that declare it by that name, so
+    existing keywords keep working unchanged. It can't interrupt a call that
+    is blocked in a single operation (a network request without a timeout).
 
     = Custom logger mappers =
 
@@ -196,7 +294,7 @@ class ParallelRunner:
     = Environment variables =
 
     | =Variable=             | =Description= |
-    | ROBOT_THREAD_WORKERS   | Number of worker threads. Read when the library is imported. Default ``4``. |
+    | ROBOT_THREAD_WORKERS   | Number of worker threads. Read when the library is imported. Default ``4``. An invalid value is ignored with a warning. |
     | ROBOT_LOGGER_MAPPER    | Default ``logger_mapper`` as a ``module.function`` path, used when the argument is not given. See `Custom logger mappers`. |
 
     = When not to use it =
@@ -210,9 +308,29 @@ class ParallelRunner:
     ROBOT_LIBRARY_VERSION = __version__
     ROBOT_LIBRARY_DOC_FORMAT = 'ROBOT'
 
+    DEFAULT_WORKERS = 4
+
     def __init__(self):
-        # Workers count from Env Var or default to 4
-        self.max_workers = int(os.getenv("ROBOT_THREAD_WORKERS", "4"))
+        self.max_workers = self._workers_from_environment()
+
+    def _workers_from_environment(self) -> int:
+        """``ROBOT_THREAD_WORKERS``, or 4. An invalid value is ignored with a
+        warning (it used to make the library import fail with a bare
+        ``invalid literal for int()``)."""
+        value = os.getenv("ROBOT_THREAD_WORKERS")
+        if _not_given(value):
+            return self.DEFAULT_WORKERS
+        try:
+            workers = int(value)
+        except ValueError:
+            workers = 0
+        if workers < 1:
+            logger.warn(
+                f"Ignoring ROBOT_THREAD_WORKERS {value!r}: expected a whole number of at least 1. "
+                f"Using {self.DEFAULT_WORKERS} workers."
+            )
+            return self.DEFAULT_WORKERS
+        return workers
 
     def run_parallel_scenarios(
         self,
@@ -225,6 +343,7 @@ class ParallelRunner:
         logger_mapper: Optional[Any] = None,
         return_values_only: bool = False,
         fail_on_error: bool = True,
+        call_timeout: Union[str, float, None] = None,
         **kwargs
     ) -> Union[List[Dict[str, Any]], Tuple[Any, ...]]:
         """Runs ``keyword`` from ``library`` concurrently, once per item or N times.
@@ -263,7 +382,14 @@ class ParallelRunner:
           when any call failed, after all calls have finished and their logs
           have been replayed. If false, return the results anyway and leave
           checking ``status`` to the caller. See `Failures`.
-        - ``**kwargs``: Any other named argument is passed to every call.
+        - ``call_timeout``: Maximum time each call may run, in Robot's time
+          format (``10s``, ``1 minute 30 seconds``, ``2.5``). A call still
+          running after it fails with ``Timed out after ...`` while the other
+          calls keep running; calls that declare ``_cancelled`` are told to
+          stop. Not given (default): no limit. See
+          `Call timeouts and cancellation`.
+        - ``**kwargs``: Any other named argument is passed to every call,
+          converted by the method's type hints like in a direct call.
 
         Returns a list of result dictionaries (see `Result format`), in call
         order: entry ``i`` belongs to ``for_loop_iterable[i]`` / repeat
@@ -276,6 +402,7 @@ class ParallelRunner:
         | ${results}=   | Run Parallel Scenarios | keyword=Check Health      | library=MyLibrary       | repeat=8 | agent_id=1 |
         | ${id1}    ${id2}    ${id3}= | Run Parallel Scenarios | keyword=Seed Record | library=MyLibrary | repeat=3 | return_values_only=True |
         | ${results}=   | Run Parallel Scenarios | keyword=Verify Agent Data | library=MyLibrary       | for_loop_iterable=${agents} | fail_on_error=False |
+        | ${results}=   | Run Parallel Scenarios | keyword=Verify Agent Data | library=MyLibrary       | for_loop_iterable=${agents} | call_timeout=30s |
         """
         # Determine items to process. NOTE: `repeat or 1` would be wrong here -
         # 0 is falsy in Python, so an explicit repeat=0 would silently fall
@@ -294,13 +421,16 @@ class ParallelRunner:
             effective_mapper = self._load_mapper_from_environment()
 
         min_level = self._resolve_thread_log_level(thread_log_level)
+        timeout_seconds = self._resolve_call_timeout(call_timeout)
 
         # Note: We must call the underlying Python method, not BuiltIn().run_keyword
         # because run_keyword is not thread-safe.
         lib_instance = self._get_library_instance_owning_keyword(keyword, library)
-        method = getattr(lib_instance, keyword.replace(" ", "_").lower())
+        method = self._get_keyword_method(lib_instance, keyword)
 
-        results = self._run_in_threads(method, list(items), effective_mapper, remove_passing_logs, min_level, kwargs)
+        results = self._run_in_threads(
+            method, list(items), effective_mapper, remove_passing_logs, min_level, kwargs, timeout_seconds
+        )
 
         # Step: Re-play logs into Robot Framework sequentially
         self._replay_logs(results, remove_passing_logs, min_level)
@@ -393,17 +523,45 @@ class ParallelRunner:
         return self._resolve_mapper(os.getenv("ROBOT_LOGGER_MAPPER"), source="ROBOT_LOGGER_MAPPER")
 
     def _get_library_instance_owning_keyword(self, keyword_name: str, library: str) -> Any:
-        method_name = keyword_name.replace(" ", "_").lower()
         lib_instance = BuiltIn().get_library_instance(library)
-        if hasattr(lib_instance, method_name):
+        if self._find_keyword_method(lib_instance, keyword_name) is not None:
             return lib_instance
         raise ValueError(f"Keyword '{keyword_name}' not found in library '{library}'")
 
+    def _get_keyword_method(self, lib_instance: Any, keyword_name: str):
+        method = self._find_keyword_method(lib_instance, keyword_name)
+        if method is None:
+            raise ValueError(f"Keyword '{keyword_name}' not found in library '{type(lib_instance).__name__}'")
+        return method
+
+    @staticmethod
+    def _find_keyword_method(lib_instance: Any, keyword_name: str):
+        """Finds the method implementing ``keyword_name``: by method name
+        (``Verify Agent Data`` -> ``verify_agent_data``), or, like Robot
+        itself, by a custom name given with ``@keyword("...")``. Names are
+        compared ignoring case, spaces and underscores."""
+        method = getattr(lib_instance, keyword_name.replace(" ", "_").lower(), None)
+        if callable(method):
+            return method
+        wanted = _normalize_name(keyword_name)
+        for attribute in dir(lib_instance):
+            # getattr_static: don't run properties just to look at them.
+            raw = inspect.getattr_static(lib_instance, attribute, None)
+            function = raw.__func__ if isinstance(raw, (staticmethod, classmethod)) else raw
+            robot_name = getattr(function, "robot_name", None)
+            if robot_name is not None:
+                matches = _normalize_name(robot_name) == wanted
+            else:
+                matches = not attribute.startswith("_") and _normalize_name(attribute) == wanted
+            if matches and callable(getattr(lib_instance, attribute, None)):
+                return getattr(lib_instance, attribute)
+        return None
+
     def _resolve_thread_log_level(self, thread_log_level: Any) -> int:
         """Returns the numeric minimum level for ``thread_log_level``. Not
         given (None, empty, "None") means every level; an unknown value is
         ignored with a warning instead of silently filtering by INFO."""
-        if thread_log_level is None or str(thread_log_level).strip().upper() in ("", "NONE"):
+        if _not_given(thread_log_level):
             return LOG_LEVELS["TRACE"]
         level = _normalize_level(thread_log_level)
         if level in LOG_LEVELS:
@@ -414,6 +572,41 @@ class ParallelRunner:
         )
         return LOG_LEVELS["TRACE"]
 
+    @staticmethod
+    def _resolve_call_timeout(call_timeout: Any) -> Optional[float]:
+        """Returns ``call_timeout`` in seconds, or None when not given. Accepts
+        Robot's time format (``10s``, ``1 minute 30 seconds``, ``1.5``)."""
+        if _not_given(call_timeout):
+            return None
+        try:
+            seconds = timestr_to_secs(call_timeout)
+        except (ValueError, DataError) as error:
+            raise ValueError(f"Invalid call_timeout {call_timeout!r}: {error}") from None
+        if seconds <= 0:
+            raise ValueError(f"call_timeout must be positive, got {call_timeout!r}.")
+        return seconds
+
+    @staticmethod
+    def _converter_for(method):
+        """Returns a function converting ``(positional, named)`` arguments by
+        the method's type hints and default values, exactly like Robot does
+        when the keyword is called directly - or None if Robot can't parse the
+        method's signature (then arguments are passed as given)."""
+        try:
+            spec = PythonArgumentParser().parse(method)
+        except Exception:
+            return None
+        return lambda positional, named: spec.convert(positional, named)
+
+    @staticmethod
+    def _accepts_cancel_event(method) -> bool:
+        """``_cancelled`` is only passed to keywords that declare it, so that
+        keywords with a fixed signature keep working."""
+        try:
+            return "_cancelled" in inspect.signature(method).parameters
+        except (TypeError, ValueError):
+            return False
+
     def _run_in_threads(
         self,
         method,
@@ -422,11 +615,17 @@ class ParallelRunner:
         remove_passing_logs: bool,
         min_level: int,
         kwargs: Dict[str, Any],
+        call_timeout: Optional[float] = None,
     ) -> List[Dict[str, Any]]:
         """
         Runs ``method`` once per item on up to ``max_workers`` daemon threads
         and returns the result dicts in call order (NOT completion order).
 
+        With ``call_timeout``, a call still running after that many seconds
+        becomes a ``FAIL`` result: its thread is abandoned (it can't be
+        killed) and a new worker takes its place, so the other calls keep
+        running ``max_workers`` at a time.
+
         If the wait is interrupted (mostly by a Robot ``[Timeout]``), the
         workers stop starting new calls, the logs collected so far are
         replayed and the exception is re-raised. Calls already running can't
@@ -437,15 +636,47 @@ class ParallelRunner:
         if self.max_workers < 1:
             raise ValueError(f"ROBOT_THREAD_WORKERS must be at least 1, got {self.max_workers}.")
 
+        count = len(items)
+        convert = self._converter_for(method)
+        if convert is not None:
+            # Once, before any thread starts: a bad named argument fails the
+            # keyword instead of every call.
+            kwargs = dict(convert([], list(kwargs.items()))[1])
+        cancel_events = [threading.Event() for _ in items] if self._accepts_cancel_event(method) else None
+
         # Created here, not in the workers, so the logs of calls that are still
-        # running can be replayed if the keyword is interrupted.
+        # running can be replayed if the keyword is interrupted or times out.
         log_buffers: List[list] = [[] for _ in items]
-        results: List[Optional[Dict[str, Any]]] = [None] * len(items)
-        started = [False] * len(items)
+        # Written by the workers. A worker writes `started_at[i]` when call i
+        # starts and `finished[i]` when it has returned - unless the main
+        # thread has timed the call out first. `claims` decides which of the
+        # two wins: dict.setdefault is atomic, so the first claim sticks.
+        started_at: List[Optional[float]] = [None] * count
+        finished: List[Optional[Dict[str, Any]]] = [None] * count
+        claims: Dict[int, str] = {}
+        # Written by the main thread only.
+        results: List[Optional[Dict[str, Any]]] = [None] * count
+
+        # What each call receives as its first argument. Only strings are
+        # converted (by the type hint, as when Robot calls the keyword with a
+        # value from a test file); other objects are passed as they are. The
+        # results keep the original item either way.
+        arguments = list(items)
         pending = queue.SimpleQueue()
-        for index in range(len(items)):
+        for index, item in enumerate(items):
+            if convert is not None and isinstance(item, str):
+                try:
+                    (arguments[index],), _ = convert([item], [])
+                except Exception as error:
+                    # Not worth starting: Robot would fail this call before running it, too.
+                    message = str(error)
+                    log_buffers[index].append(("ERROR", f"Thread failed for item {item}: {message}"))
+                    started_at[index] = time.monotonic()
+                    finished[index] = {"status": "FAIL", "item": item, "logs": log_buffers[index], "error": message}
+                    continue
             pending.put(index)
         stop = threading.Event()
+        workers_started = 0
 
         def worker():
             while not stop.is_set():
@@ -453,27 +684,79 @@ class ParallelRunner:
                     index = pending.get_nowait()
                 except queue.Empty:
                     return
-                started[index] = True
-                results[index] = self._execute_and_capture(
-                    method, items[index], logger_mapper, log_buffers[index], kwargs
+                call_kwargs = kwargs if cancel_events is None else {**kwargs, "_cancelled": cancel_events[index]}
+                started_at[index] = time.monotonic()
+                result = self._execute_and_capture(
+                    method, items[index], logger_mapper, log_buffers[index], call_kwargs, arguments[index]
                 )
+                if claims.setdefault(index, _WORKER) != _WORKER:
+                    # The call timed out and a new worker took this thread's
+                    # place: stop here, so no more than max_workers calls run.
+                    return
+                finished[index] = result
+
+        def start_worker():
+            nonlocal workers_started
+            workers_started += 1
+            threading.Thread(target=worker, name=f"ParallelRunner-worker-{workers_started}", daemon=True).start()
 
         try:
-            for number in range(min(self.max_workers, len(items))):
-                threading.Thread(target=worker, name=f"ParallelRunner-worker-{number + 1}", daemon=True).start()
+            for _ in range(min(self.max_workers, count)):
+                start_worker()
             # Deliberately no lock, Event or Future wait here: a timeout raised
             # asynchronously while such a wait holds an internal lock could
             # leave it locked forever. Short sleeps and plain reads are safe.
-            for index in range(len(items)):
-                while results[index] is None:
+            remaining = count
+            next_unstarted = 0
+            running: List[int] = []
+            while remaining:
+                # Calls start in index order (FIFO queue), so started calls are
+                # picked up by moving a pointer instead of scanning every slot.
+                while next_unstarted < count and started_at[next_unstarted] is not None:
+                    running.append(next_unstarted)
+                    next_unstarted += 1
+                now = time.monotonic()
+                still_running = []
+                for index in running:
+                    if finished[index] is not None:
+                        results[index] = finished[index]
+                        remaining -= 1
+                    elif (
+                        call_timeout is not None
+                        and now - started_at[index] >= call_timeout
+                        and claims.setdefault(index, _MAIN) == _MAIN
+                    ):
+                        results[index] = self._timed_out_result(items[index], log_buffers[index], call_timeout)
+                        remaining -= 1
+                        if cancel_events is not None:
+                            cancel_events[index].set()
+                        if not pending.empty():
+                            start_worker()
+                    else:
+                        still_running.append(index)
+                running = still_running
+                if remaining:
                     time.sleep(_POLL_INTERVAL)
         except BaseException as error:
             stop.set()
-            self._replay_interrupted(items, results, started, log_buffers, error, remove_passing_logs, min_level)
+            if cancel_events is not None:
+                for event in cancel_events:
+                    event.set()
+            self._replay_interrupted(
+                items, results, finished, started_at, log_buffers, error, remove_passing_logs, min_level
+            )
             raise
         return results
 
-    def _replay_interrupted(self, items, results, started, log_buffers, error, remove_passing_logs, min_level):
+    @staticmethod
+    def _timed_out_result(item, log_buffer: list, call_timeout: float) -> Dict[str, Any]:
+        duration = secs_to_timestr(call_timeout)
+        logs = list(log_buffer)
+        logs.append(("ERROR", f"Call for item {item} timed out after {duration} (call_timeout); "
+                              "it keeps running in the background"))
+        return {"status": "FAIL", "item": item, "logs": logs, "error": f"Timed out after {duration}"}
+
+    def _replay_interrupted(self, items, results, finished, started_at, log_buffers, error, remove_passing_logs, min_level):
         """Replays what the calls logged before the keyword was interrupted.
         Calls that never started are only counted, not listed one by one."""
         # On Windows Robot raises the timeout as a bare class, without message.
@@ -481,12 +764,12 @@ class ParallelRunner:
         partial = []
         running = not_started = 0
         for index, item in enumerate(items):
-            # Read the result before `started`: a call that finishes in between
-            # is then reported as still running, never as not started.
-            result = results[index]
+            # Read the results before `started_at`: a call that finishes in
+            # between is then reported as still running, never as not started.
+            result = results[index] or finished[index]
             if result is not None:
                 partial.append(result)
-            elif started[index]:
+            elif started_at[index] is not None:
                 running += 1
                 logs = list(log_buffers[index])
                 logs.append(("ERROR", f"Call for item {item} did not finish: still running when the keyword was interrupted ({reason})"))
@@ -500,14 +783,19 @@ class ParallelRunner:
         self._replay_logs(partial, remove_passing_logs, min_level)
 
     def _execute_and_capture(
-        self, method, item, logger_mapper: Optional[Any], log_buffer: list, kwargs: Dict[str, Any]
+        self, method, item, logger_mapper: Optional[Any], log_buffer: list, kwargs: Dict[str, Any],
+        argument: Any = _NOT_SET,
     ) -> Dict[str, Any]:
         """Worker wrapper to capture logs and results.
 
-        ``kwargs`` is a dict, not ``**kwargs``, so a keyword argument that
-        happens to be called ``method``, ``item`` or ``log_buffer`` can't clash
-        with this method's own parameters.
+        ``argument`` is what the call receives as its first argument (``item``
+        converted by its type hint), ``item`` what the result reports. ``kwargs``
+        is a dict, not ``**kwargs``, so a keyword argument that happens to be
+        called ``method``, ``item`` or ``log_buffer`` can't clash with this
+        method's own parameters.
         """
+        if argument is _NOT_SET:
+            argument = item
         # Injection of a custom logger into the thread
         def thread_log(msg, level="INFO"):
             # Filter out IGNORE (sv=0) level logs. Other levels are kept as
@@ -519,7 +807,7 @@ class ParallelRunner:
         effective_logger = logger_mapper if logger_mapper else thread_log
 
         try:
-            result = method(item, _logger=effective_logger, **kwargs)
+            result = method(argument, _logger=effective_logger, **kwargs)
             return {"status": "PASS", "item": item, "logs": log_buffer, "result": result}
         # BaseException, not Exception: whatever the call raises (even
         # SystemExit), the worker must report a result, or the main thread