`Steps` stack is not thread-safe

[hamztouiz]

Description

The global Steps._stack in labgrid/step.py is a plain Python list shared across all threads. I'm hitting an AssertionError in Steps.pop() intermittently, and I believe it is caused by a race condition between threads.

I'm not sure if my usage of USBVideoDriver is the intended one — I'm running a continuous background image capture (OpenCV/GStreamer) while simultaneously calling other @step-decorated drivers from the main thread. It's possible this use case was not anticipated, and that Steps was designed assuming single-threaded usage only.

That said, if other scenarios can also trigger background threads (e.g. async callbacks, GStreamer internals), this could affect more users.

My setup

• USBVideoDriver is used to capture frames continuously in a background thread (via OpenCV/GStreamer)
• While the capture is running, the main thread calls USBSDMuxDriver.set_mode() (or any other @step-decorated method)
• Both threads end up pushing/popping on the same shared _stack, corrupting its order

Traceback

File ".../labgrid/step.py", line 222, in wrapper
    step.stop()
File ".../labgrid/step.py", line 186, in stop
    steps.pop(self)
File ".../labgrid/step.py", line 29, in pop
    assert self._stack[-1] is step
AssertionError

Environment

• labgrid version: 25.0.1
• Python: 3.13
• OS: Ubuntu
• Test runner: Robot Framework

Question

Is it intentional that Steps is not thread-safe? Is my usage of USBVideoDriver in a background capture thread considered unsupported?

If making _stack thread-local is acceptable, I'd be happy to submit a PR:

import threading

class Steps:
    def __init__(self):
        self._local = threading.local()
        self._subscribers = []

    @property
    def _stack(self):
        if not hasattr(self._local, 'stack'):
            self._local.stack = []
        return self._local.stack

[mbodmer]

I have multiple targets which I use in parallel (e.g. reboot all targets into u-boot, or execute an ssh command on all of them) and also would need a threadsafe Steps stack for this.

For now I use a monkeypatch in conftest.py based on your proposal, like this:

import importlib
import threading
import warnings

try:
    _lg_step = importlib.import_module("labgrid.step")
    Steps = getattr(_lg_step, "Steps", None)
    if Steps is None:
        raise AttributeError("labgrid.step module has no attribute 'Steps'")

    if not getattr(Steps, "_stack_is_threadlocal", False):
        Steps._thread_local = threading.local()

        def _stack(self):
            tl = self._thread_local
            if not hasattr(tl, "stack"):
                tl.stack = []
            return tl.stack

        Steps._stack = property(_stack)
        Steps._stack_is_threadlocal = True

        # If an existing instance attribute is present on the instance dict,
        # remove it so the descriptor takes effect.
        steps_inst = getattr(_lg_step, "steps", None)
        if steps_inst is not None:
            inst_dict = getattr(steps_inst, "__dict__", {})
            inst_dict.pop("_stack", None)
except Exception as e:
    warnings.warn(f"labgrid Steps thread-local patch failed: {e}")

[jluebbe]

labgrid in general is not intended to be used from multiple threads, so this is not supported. You can use multiple processes instead.

[mbodmer]

multiple processes work on the same labgrid instance?

[jluebbe]

If you mean one place on the same coordinator, yes. It's very common to have e.g. one labgrid-client console open while using other labgrid-client commands in a different shell.

[hamztouiz]

Thanks for the clarification. We will look for another solution on our end.

For context, our main use case is collecting messages from a UART in a non-blocking way while other drivers are active, we observed this issue specifically when reading from a serial interface using SerialDriver in a background thread, while the main thread was performing other driver operations. We haven't found an elegant solution yet without spawning a background thread, but we'll keep looking.

Thanks again for the quick responses.

[mbodmer]

Thanks for the feedback on this. I wonder how I could use multiple labgrid clients from a single pytest run, probably without the plugin? Is there an example somewhere?

[jluebbe]

Thanks for the feedback on this. I wonder how I could use multiple labgrid clients from a single pytest run, probably without the plugin? Is there an example somewhere?

labgrid-client won't help you for pytest test cases. Not supporting multi-threading in the labgrid API is a design decision to keep the complexity managable.

[jluebbe]

For context, our main use case is collecting messages from a UART in a non-blocking way while other drivers are active, we observed this issue specifically when reading from a serial interface using SerialDriver in a background thread, while the main thread was performing other driver operations. We haven't found an elegant solution yet without spawning a background thread, but we'll keep looking.

AFAIK, PySerial already uses a thread internally to buffer received data, so if you don't need process the output concurrently (i.e. only after you're done with the other driver), it should already work.