From 50815a267ebb7a4322020cf44da2e998b0af8adc Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 09:09:14 +0100 Subject: [PATCH 01/19] Do not close instruments again when they are garbage collected Instrument.__del__ called close unconditionally. Closing an instrument strips it, which breaks its reference cycles, so the closed instrument is freed later and __del__ then closed it a second time. That reran the close methods of drivers at an arbitrary later point in time, possibly after the name or resources of the instrument had been reused by a new instrument. Instrument.close now marks the instrument as closed after stripping it, and __del__ only closes instruments that have not been closed. IPToVisa reimplemented the tail of Instrument.close and now calls it instead, so that it is marked as closed too. The docstring of __del__ now explains why instruments should be closed explicitly: they are only collected by the cyclic garbage collector, and finalizers such as the one closing the VISA handle run before __del__, so close can no longer communicate with the instrument at that point. The comment in remove_instance claimed that the garbage collector clears all weak references before finalizing an object. Python 3.15 keeps weak references without callbacks until after finalizing, which is harmless since weak containers iterate over a copy from Python 3.14. Correct it. --- docs/changes/newsfragments/+gc_close.improved | 5 ++ src/qcodes/instrument/instrument.py | 41 +++++++++++++---- src/qcodes/instrument/ip_to_visa.py | 9 +--- tests/test_instrument.py | 46 +++++++++++++++++++ 4 files changed, 86 insertions(+), 15 deletions(-) create mode 100644 docs/changes/newsfragments/+gc_close.improved diff --git a/docs/changes/newsfragments/+gc_close.improved b/docs/changes/newsfragments/+gc_close.improved new file mode 100644 index 00000000000..d482c3db328 --- /dev/null +++ b/docs/changes/newsfragments/+gc_close.improved @@ -0,0 +1,5 @@ +Instruments that have been closed are no longer closed a second time when they are garbage collected. +Previously, the ``close`` method of a driver could run again at an arbitrary later point in time, +possibly after the name or the resources of the instrument had been reused by a new instrument. +Instruments that are garbage collected without having been closed are still closed, but +instruments should always be closed explicitly, e.g. with ``close`` or ``Instrument.close_all``. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index fc3acfa9043..a614bfca4e7 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -62,6 +62,8 @@ class Instrument(InstrumentBase, metaclass=instrument_meta_class): ) _type: type[Instrument] | None = None _instances: ClassVar[weakref.WeakSet[Instrument]] = weakref.WeakSet() + # Name mangled so that it cannot clash with attributes of subclasses. + __closed: bool = False def __init__(self, name: str, **kwargs: Unpack[InstrumentBaseKWArgs]) -> None: self._t0 = time.time() @@ -149,7 +151,24 @@ def __repr__(self) -> str: return f"<{type(self).__name__}: {self.name}>" def __del__(self) -> None: - """Close the instrument and remove its instance record.""" + """ + Close the instrument if it is garbage collected without having been + closed, so that its resources are freed. + + Do not rely on this: always close instruments explicitly with + :meth:`close` (or :meth:`close_all`). As instruments reference + themselves through their parameters, they are only garbage collected + when the cyclic garbage collector runs, which may be much later and on + any thread. At that point, connections that are closed by a finalizer, + such as the VISA handle of a :class:`.VisaInstrument`, have already + been closed, so :meth:`close` can no longer communicate with the + instrument. + """ + if self.__closed: + # Closing it again would rerun the close methods of subclasses at + # an arbitrary point in time, possibly after the name or the + # resources of the instrument have been reused. + return try: self.close() except BaseException: # noqa: BLE001, S110 @@ -185,6 +204,7 @@ def close(self) -> None: strip_attrs(channel, whitelist=["_short_name", "_parent"]) strip_attrs(self, whitelist=["_short_name"]) + self.__closed = True @classmethod def close_all( @@ -290,14 +310,19 @@ def remove_instance(cls, instance: Instrument) -> None: """ if weakref.getweakrefcount(instance) == 0: # Instances are only recorded through weak references, so there is - # nothing to remove. This is the case when the garbage collector - # finalizes the instance, since it clears all weak references to - # the instance before that. Leave the records alone then: before - # Python 3.14, weak containers postpone removing dead entries while - # being iterated over, but most of their methods apply postponed - # removals right away. That would make an iteration that the - # garbage collection interrupted fail with + # nothing to remove. Leave the records alone then, since this is + # also the case when the garbage collector finalizes (and thereby + # closes) the instance in the middle of another operation, which + # may be an iteration over the records. Before Python 3.14, weak + # containers postpone removing dead entries while being iterated + # over, but most of their methods apply postponed removals right + # away, which would make the interrupted iteration fail with # "RuntimeError: dictionary changed size during iteration". + # Those Python versions clear all weak references to an object + # before finalizing it. Python 3.15 keeps weak references without + # callbacks until after finalizing (python/cpython#135552), but + # from Python 3.14 weak containers iterate over a copy + # (python/cpython#89967), so updating the records is safe there. return if instance in getattr(cls, "_instances", weakref.WeakSet()): diff --git a/src/qcodes/instrument/ip_to_visa.py b/src/qcodes/instrument/ip_to_visa.py index 5f66698dd24..3548c60fa2e 100644 --- a/src/qcodes/instrument/ip_to_visa.py +++ b/src/qcodes/instrument/ip_to_visa.py @@ -5,7 +5,6 @@ import qcodes.validators as vals from qcodes.logger import get_instrument_logger -from qcodes.utils import strip_attrs from .instrument import Instrument from .ip import IPInstrument @@ -108,9 +107,5 @@ def close(self) -> None: # https://github.com/pyvisa/pyvisa-sim/issues/82 self.resource_manager.visalib._init() - # Instrument close - if hasattr(self, "connection") and hasattr(self.connection, "close"): - self.connection.close() - - self.remove_instance(self) - strip_attrs(self, whitelist=["_short_name"]) + # skip the close method of IPInstrument + Instrument.close(self) diff --git a/tests/test_instrument.py b/tests/test_instrument.py index be6d9ec192a..3ad6f50376d 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -715,6 +715,52 @@ def use_some_instrument() -> None: assert len(Instrument._all_instruments) == 0 +def _instrument_class_recording_close(closed: list[str]) -> type[Instrument]: + """ + Create an instrument class that records the name of each instrument that + is closed in ``closed``, also when the instrument has been stripped by an + earlier close. + """ + + class InstrumentRecordingClose(Instrument): + def close(self) -> None: + closed.append(self.name) + super().close() + + return InstrumentRecordingClose + + +@pytest.mark.usefixtures("close_before_and_after") +def test_garbage_collecting_unclosed_instrument_closes_it() -> None: + closed: list[str] = [] + _instrument_class_recording_close(closed)("unclosed") + + gc.collect() + + assert closed == ["unclosed"] + assert not Instrument.exist("unclosed") + + +@pytest.mark.usefixtures("close_before_and_after") +def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: + """ + An instrument that has been closed explicitly is not closed again when + garbage collected, which may happen after its name has been reused. + """ + closed: list[str] = [] + instrument_class = _instrument_class_recording_close(closed) + old_instrument = instrument_class("instr") + old_instrument.close() + new_instrument = instrument_class("instr") + + del old_instrument + gc.collect() + + assert closed == ["instr"] + assert Instrument.find_instrument("instr") is new_instrument + new_instrument.close() + + def test_snapshot_and_meta_attrs() -> None: """Test snapshot of InstrumentBase contains _meta_attrs attributes""" instr = InstrumentBase("instr", label="Label") From e32d8a626bf8cd57a6f2051cff828bcec94a9b83 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 09:11:49 +0100 Subject: [PATCH 02/19] Fully close Galil and MiniCircuits USB HID instruments The close methods of GalilMotionController and MiniCircuitsHIDMixin only closed the connection to the device and did not call super().close(). The instruments therefore stayed registered, so their names could not be reused until they were garbage collected, and as they were never marked as closed, the garbage collector closed their connections a second time. Call super().close() after closing the connection, and test closing both drivers with fakes of the vendor libraries, which cannot be installed in CI. --- .../+galil_minicircuits_close.improved_driver | 3 + .../instrument_drivers/Galil/dmc_41x3.py | 4 +- .../Minicircuits/USBHIDMixin.py | 2 + tests/drivers/test_galil_dmc_41x3.py | 66 +++++++++++++ .../test_minicircuits_usb_hid_mixin.py | 92 +++++++++++++++++++ 5 files changed, 166 insertions(+), 1 deletion(-) create mode 100644 docs/changes/newsfragments/+galil_minicircuits_close.improved_driver create mode 100644 tests/drivers/test_galil_dmc_41x3.py create mode 100644 tests/drivers/test_minicircuits_usb_hid_mixin.py diff --git a/docs/changes/newsfragments/+galil_minicircuits_close.improved_driver b/docs/changes/newsfragments/+galil_minicircuits_close.improved_driver new file mode 100644 index 00000000000..8db49be2919 --- /dev/null +++ b/docs/changes/newsfragments/+galil_minicircuits_close.improved_driver @@ -0,0 +1,3 @@ +``GalilMotionController`` and the MiniCircuits USB HID drivers (``MiniCircuitsHIDMixin`` subclasses) +now fully close the instrument in ``close``. Previously, they only closed the connection, so the +instrument stayed registered and its name could not be reused until it was garbage collected. diff --git a/src/qcodes/instrument_drivers/Galil/dmc_41x3.py b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py index 758a06424be..b2bbae37b55 100644 --- a/src/qcodes/instrument_drivers/Galil/dmc_41x3.py +++ b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py @@ -176,9 +176,11 @@ def timeout(self, val: int) -> None: def close(self) -> None: """ - Close connection to the instrument + Close connection to the instrument and irreversibly tear down the + instrument. """ self.g.GClose() + super().close() def motion_complete(self, axes: str) -> None: """ diff --git a/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py index b5de6d55eec..351fa47deff 100644 --- a/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py +++ b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py @@ -165,7 +165,9 @@ def ask_raw(self, cmd: str) -> str: return self._unpack_string(response) def close(self) -> None: + """Disconnect and irreversibly tear down the instrument.""" self._device.close() + super().close() @classmethod def enumerate_devices(cls) -> list[str]: diff --git a/tests/drivers/test_galil_dmc_41x3.py b/tests/drivers/test_galil_dmc_41x3.py new file mode 100644 index 00000000000..3a71e9b1276 --- /dev/null +++ b/tests/drivers/test_galil_dmc_41x3.py @@ -0,0 +1,66 @@ +"""Tests for the Galil DMC-41x3 driver using a fake ``gclib`` module. + +The driver requires the vendor ``gclib`` package, which cannot be installed +from PyPI, so it is replaced by a minimal fake that records the calls made. +""" + +import importlib +import sys +import types +from typing import TYPE_CHECKING + +import pytest + +from qcodes.instrument import Instrument + +if TYPE_CHECKING: + from collections.abc import Generator + +_DRIVER_MODULE = "qcodes.instrument_drivers.Galil.dmc_41x3" + + +class _FakeGclibConnection: + def __init__(self) -> None: + self.is_open = False + + def GOpen(self, address: str) -> None: + self.is_open = True + + def GClose(self) -> None: + self.is_open = False + + def GInfo(self) -> str: + return "192.168.1.2, DMC4133 Rev 1.0b, 12345" + + +@pytest.fixture(name="driver_module") +def _driver_module_with_fake_gclib( + monkeypatch: pytest.MonkeyPatch, +) -> "Generator[types.ModuleType, None, None]": + fake_gclib = types.ModuleType("gclib") + fake_gclib.py = _FakeGclibConnection # type: ignore[attr-defined] + fake_gclib.GclibError = Exception # type: ignore[attr-defined] + monkeypatch.setitem(sys.modules, "gclib", fake_gclib) + for name in ("qcodes.instrument_drivers.Galil", _DRIVER_MODULE): + monkeypatch.delitem(sys.modules, name, raising=False) + try: + yield importlib.import_module(_DRIVER_MODULE) + finally: + # Do not leave the driver bound to the fake module behind. + for name in ("qcodes.instrument_drivers.Galil", _DRIVER_MODULE): + sys.modules.pop(name, None) + + +def test_close_closes_connection_and_unregisters_instrument( + driver_module: types.ModuleType, +) -> None: + controller = driver_module.GalilMotionController("galil", address="192.168.1.2") + connection = controller.g + assert connection.is_open + + controller.close() + + assert not connection.is_open + assert not Instrument.exist("galil") + # the name can be reused once the instrument has been closed + driver_module.GalilMotionController("galil", address="192.168.1.2").close() diff --git a/tests/drivers/test_minicircuits_usb_hid_mixin.py b/tests/drivers/test_minicircuits_usb_hid_mixin.py new file mode 100644 index 00000000000..933809b9a4c --- /dev/null +++ b/tests/drivers/test_minicircuits_usb_hid_mixin.py @@ -0,0 +1,92 @@ +"""Tests for the MiniCircuits USB HID mixin using fake hardware libraries. + +The mixin requires ``pywinusb`` on Windows and a connected device, and the +``Minicircuits`` package imports ``clr`` from ``pythonnet``, so both are +replaced by minimal fakes. The fake device records the calls made. +""" + +import importlib +import sys +import types +from typing import TYPE_CHECKING, Any + +import pytest + +from qcodes.instrument import Instrument + +if TYPE_CHECKING: + from collections.abc import Generator + +_PACKAGE = "qcodes.instrument_drivers.Minicircuits" +_MIXIN_MODULE = f"{_PACKAGE}.USBHIDMixin" + + +class _FakeHidDevice: + def __init__(self) -> None: + self.is_open = False + + def open(self) -> None: + self.is_open = True + + def close(self) -> None: + self.is_open = False + + def set_raw_data_handler(self, handler: Any) -> None: + pass + + +class _FakeHid: + def __init__(self) -> None: + self.device = _FakeHidDevice() + + def HidDeviceFilter(self, **kwargs: Any) -> Any: + device = self.device + + class _Filter: + def get_devices(self) -> list[_FakeHidDevice]: + return [device] + + return _Filter() + + +def _driver_modules() -> list[str]: + return [ + name + for name in sys.modules + if name == _PACKAGE or name.startswith(f"{_PACKAGE}.") + ] + + +@pytest.fixture(name="fake_hid") +def _fake_hid(monkeypatch: pytest.MonkeyPatch) -> "Generator[_FakeHid, None, None]": + monkeypatch.setitem(sys.modules, "clr", types.ModuleType("clr")) + for name in _driver_modules(): + monkeypatch.delitem(sys.modules, name) + try: + mixin_module = importlib.import_module(_MIXIN_MODULE) + fake_hid = _FakeHid() + monkeypatch.setattr(mixin_module, "hid", fake_hid) + # the real check requires Windows and an installed pywinusb + monkeypatch.setattr( + mixin_module.MiniCircuitsHIDMixin, + "_check_hid_import", + staticmethod(lambda: None), + ) + yield fake_hid + finally: + # Do not leave the drivers bound to the fake modules behind. + for name in _driver_modules(): + sys.modules.pop(name) + + +def test_close_closes_device_and_unregisters_instrument(fake_hid: _FakeHid) -> None: + mixin_class = importlib.import_module(_MIXIN_MODULE).MiniCircuitsHIDMixin + instrument = mixin_class("minicircuits") + assert fake_hid.device.is_open + + instrument.close() + + assert not fake_hid.device.is_open + assert not Instrument.exist("minicircuits") + # the name can be reused once the instrument has been closed + mixin_class("minicircuits").close() From 70cd16a2bafa7260d858d79e6c2345c4fbdff073 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 10:15:29 +0100 Subject: [PATCH 03/19] Warn when the garbage collector closes an unclosed instrument Closing instruments when they are garbage collected is only best effort: it happens at an arbitrary later point in time, on any thread, and after finalizers such as the one closing the VISA handle have run, so close can no longer communicate with the instrument. To encourage closing instruments explicitly, Instrument.__del__ now emits a ResourceWarning, like unclosed files do, before closing an instrument that was not closed. The instrument is still closed if the warning is turned into an error. Instruments whose initialization failed are still closed without a warning, since they were never handed to the user. To tell these apart, the boolean tracking whether an instrument has been closed is replaced by a single lifecycle state: initializing, open (registered and handed to the user) or closed. Tests that deliberately leave instruments to the garbage collector now expect the warning. Forcing a garbage collection after every test shows that no other test leaks an instrument. --- .../+gc_resource_warning.improved | 7 ++ src/qcodes/instrument/instrument.py | 62 +++++++++++++--- tests/test_instrument.py | 70 ++++++++++++++++--- tests/test_visa.py | 5 +- 4 files changed, 121 insertions(+), 23 deletions(-) create mode 100644 docs/changes/newsfragments/+gc_resource_warning.improved diff --git a/docs/changes/newsfragments/+gc_resource_warning.improved b/docs/changes/newsfragments/+gc_resource_warning.improved new file mode 100644 index 00000000000..5fca80695f1 --- /dev/null +++ b/docs/changes/newsfragments/+gc_resource_warning.improved @@ -0,0 +1,7 @@ +Instruments that are garbage collected without having been closed now emit a ``ResourceWarning`` +(like unclosed files) when the garbage collector closes them. Garbage collection only closes +instruments on a best effort basis, at an arbitrary later point in time, so instruments should +always be closed explicitly, e.g. with ``close`` or ``Instrument.close_all``. +Python hides ``ResourceWarning`` by default, but it is shown e.g. by pytest and in Python's +development mode. Test suites that turn warnings into errors report it as an exception ignored in +``Instrument.__del__``. Instruments that fail to initialize are still closed without a warning. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index a614bfca4e7..67563b78bf7 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -4,7 +4,9 @@ import logging import time +import warnings import weakref +from enum import Enum, auto from typing import TYPE_CHECKING, Any, ClassVar, Protocol, overload from qcodes.utils import strip_attrs @@ -31,6 +33,23 @@ def ask(self, cmd: str) -> str: ... def write(self, cmd: str) -> None: ... +class _InstrumentState(Enum): + """The stages of the lifecycle of an :class:`Instrument`.""" + + INITIALIZING = auto() + """ + The instrument is being initialized and has not been handed to the user. + It stays in this state if its initialization fails. + """ + OPEN = auto() + """ + The instrument has been initialized, registered and handed to the user, + who is responsible for closing it. + """ + CLOSED = auto() + """The instrument has been closed and its attributes stripped.""" + + # a metaclass that overrides __call__ means that we lose # both the args and return type hints. # Since our metaclass does not modify the signature @@ -63,7 +82,7 @@ class Instrument(InstrumentBase, metaclass=instrument_meta_class): _type: type[Instrument] | None = None _instances: ClassVar[weakref.WeakSet[Instrument]] = weakref.WeakSet() # Name mangled so that it cannot clash with attributes of subclasses. - __closed: bool = False + __state: _InstrumentState = _InstrumentState.INITIALIZING def __init__(self, name: str, **kwargs: Unpack[InstrumentBaseKWArgs]) -> None: self._t0 = time.time() @@ -153,7 +172,8 @@ def __repr__(self) -> str: def __del__(self) -> None: """ Close the instrument if it is garbage collected without having been - closed, so that its resources are freed. + closed, so that its resources are freed, and emit a + :class:`ResourceWarning` about it. Do not rely on this: always close instruments explicitly with :meth:`close` (or :meth:`close_all`). As instruments reference @@ -164,19 +184,37 @@ def __del__(self) -> None: been closed, so :meth:`close` can no longer communicate with the instrument. """ - if self.__closed: + if self.__state is _InstrumentState.CLOSED: # Closing it again would rerun the close methods of subclasses at # an arbitrary point in time, possibly after the name or the # resources of the instrument have been reused. return try: - self.close() - except BaseException: # noqa: BLE001, S110 - # we want to avoid __del__ raising any exceptions - # it might be possible to avoid this see - # https://docs.python.org/3/reference/datamodel.html#object.__del - # however that would require careful testing. - pass + # Instruments that failed to initialize have never been handed to + # the user, who could therefore not have closed them. + if self.__state is _InstrumentState.OPEN: + # Like for unclosed files, the instrument is still closed if + # the warning is turned into an error, which is then reported + # as an exception ignored in __del__. + warnings.warn( + f"unclosed instrument {self!r}. Close instruments " + "explicitly with close() or Instrument.close_all() " + "instead of relying on the garbage collector.", + ResourceWarning, + # Point at this method rather than at whatever code + # happened to trigger the garbage collection. + stacklevel=1, + source=self, + ) + finally: + try: + self.close() + except BaseException: # noqa: BLE001, S110 + # we want to avoid __del__ raising any exceptions + # it might be possible to avoid this see + # https://docs.python.org/3/reference/datamodel.html#object.__del + # however that would require careful testing. + pass def close(self) -> None: """ @@ -204,7 +242,8 @@ def close(self) -> None: strip_attrs(channel, whitelist=["_short_name", "_parent"]) strip_attrs(self, whitelist=["_short_name"]) - self.__closed = True + # after stripping the attributes, which would remove the state again + self.__state = _InstrumentState.CLOSED @classmethod def close_all( @@ -280,6 +319,7 @@ def record_instance(cls, instance: Instrument) -> None: cls._type = cls cls._instances = weakref.WeakSet() cls._instances.add(instance) + instance.__state = _InstrumentState.OPEN @classmethod def instances(cls: type[Self]) -> list[Self]: diff --git a/tests/test_instrument.py b/tests/test_instrument.py index 3ad6f50376d..f4979b4c296 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -9,6 +9,7 @@ import io import logging import re +import warnings import weakref from typing import TYPE_CHECKING, Any, assert_type from weakref import WeakValueDictionary @@ -625,7 +626,10 @@ def test_close_when_gc_finalizes_instrument_during_registry_iteration( assert not Instrument.exist("dummy") DummyInstrument(name="dummy", gates=["dac1"]).close() - gc.collect() + with pytest.warns( + ResourceWarning, match="unclosed instrument " + ): + gc.collect() assert len(Instrument._all_instruments) == 0 @@ -643,7 +647,10 @@ def test_close_all_when_gc_finalizes_instrument_during_registry_iteration( _leak_instrument("leaked") parabola = MockParabola("parabola") - Instrument.close_all() + with pytest.warns( + ResourceWarning, match="unclosed instrument " + ): + Instrument.close_all() assert registry.collected_garbage assert not Instrument.is_valid(dummy) @@ -711,18 +718,27 @@ def use_some_instrument() -> None: assert len(Instrument._all_instruments) == 0 use_some_instrument() - gc.collect() + with pytest.warns(ResourceWarning, match="unclosed instrument"): + gc.collect() assert len(Instrument._all_instruments) == 0 -def _instrument_class_recording_close(closed: list[str]) -> type[Instrument]: +def _instrument_class_recording_close( + closed: list[str], *, fail_to_initialize: bool = False +) -> type[Instrument]: """ Create an instrument class that records the name of each instrument that is closed in ``closed``, also when the instrument has been stripped by an - earlier close. + earlier close. If ``fail_to_initialize`` is True, initializing an + instrument of the class raises a ``RuntimeError``. """ class InstrumentRecordingClose(Instrument): + def __init__(self, name: str) -> None: + super().__init__(name) + if fail_to_initialize: + raise RuntimeError("Failed to initialize") + def close(self) -> None: closed.append(self.name) super().close() @@ -731,21 +747,50 @@ def close(self) -> None: @pytest.mark.usefixtures("close_before_and_after") -def test_garbage_collecting_unclosed_instrument_closes_it() -> None: +def test_garbage_collecting_unclosed_instrument_closes_it_and_warns() -> None: closed: list[str] = [] _instrument_class_recording_close(closed)("unclosed") - gc.collect() + with pytest.warns( + ResourceWarning, + match=r"unclosed instrument \. " + r"Close instruments explicitly", + ): + gc.collect() assert closed == ["unclosed"] assert not Instrument.exist("unclosed") +@pytest.mark.usefixtures("close_before_and_after") +def test_garbage_collecting_instrument_that_failed_to_initialize_does_not_warn() -> ( + None +): + """ + An instrument whose initialization failed is still closed when garbage + collected, but without a warning, as it was never handed to the user who + could therefore not have closed it. + """ + closed: list[str] = [] + failing_class = _instrument_class_recording_close(closed, fail_to_initialize=True) + + with pytest.raises(RuntimeError, match="Failed to initialize"): + failing_class("failing") + + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + gc.collect() + + assert closed == ["failing"] + assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] + + @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ - An instrument that has been closed explicitly is not closed again when - garbage collected, which may happen after its name has been reused. + An instrument that has been closed explicitly is neither closed again nor + warned about when garbage collected, which may happen after its name has + been reused. """ closed: list[str] = [] instrument_class = _instrument_class_recording_close(closed) @@ -753,10 +798,13 @@ def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: old_instrument.close() new_instrument = instrument_class("instr") - del old_instrument - gc.collect() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter("always") + del old_instrument + gc.collect() assert closed == ["instr"] + assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] assert Instrument.find_instrument("instr") is new_instrument new_instrument.close() diff --git a/tests/test_visa.py b/tests/test_visa.py index 0466891ce6b..c146b4de2ee 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -161,7 +161,10 @@ def use_magnet() -> pyvisa.ResourceManager: caplog.clear() with caplog.at_level(logging.INFO, logger="qcodes.instrument.visa"): rm = use_magnet() - gc.collect() + with pytest.warns( + ResourceWarning, match="unclosed instrument " + ): + gc.collect() # at this stage the instrument created in use_magnet has gone out of scope # and we have triggered an explicit gc so the weakref.finalize function # has been triggered. We test this From 5a49b837f85262592e5d9c7d765aa7f5f6c361dd Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 10:46:24 +0100 Subject: [PATCH 04/19] Close instruments right away when their initialization fails An instrument whose __init__ raised was only closed when the garbage collector finalized it, which may be much later. Until then, it kept the resources that it had acquired before the failure. For example, a VISA instrument that failed after connecting kept its VISA handle open, so creating the instrument again for a resource that can only be opened once failed until the garbage collector had run. InstrumentMeta.__call__ now creates and initializes the instance like type.__call__ does, so that it can close the instance if __init__ raises, before re-raising the error. As the instrument may only be partly initialized, closing it may fail too. That is added as a note to the error of the initialization, and closing is not retried when the instrument is garbage collected. VisaInstrument no longer closes itself when connecting fails, since the metaclass now does that for any failure during initialization. --- .../+close_on_failed_init.improved | 5 ++ src/qcodes/instrument/instrument.py | 41 ++++++++++++++--- src/qcodes/instrument/instrument_meta.py | 29 ++++++++---- src/qcodes/instrument/visa.py | 2 +- tests/test_instrument.py | 46 ++++++++++++++++--- tests/test_visa.py | 30 ++++++++++++ 6 files changed, 129 insertions(+), 24 deletions(-) create mode 100644 docs/changes/newsfragments/+close_on_failed_init.improved diff --git a/docs/changes/newsfragments/+close_on_failed_init.improved b/docs/changes/newsfragments/+close_on_failed_init.improved new file mode 100644 index 00000000000..5ee4478dce4 --- /dev/null +++ b/docs/changes/newsfragments/+close_on_failed_init.improved @@ -0,0 +1,5 @@ +Instruments whose initialization fails are now closed right away, so that the resources they +acquired before the failure, such as an open VISA connection, are freed immediately rather than +when the instrument is garbage collected. Previously, retrying to create an instrument for a +resource that can only be opened once could fail until the garbage collector had run. +If closing the instrument fails too, this is added as a note to the error of the initialization. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 67563b78bf7..e1269dff08e 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -37,17 +37,17 @@ class _InstrumentState(Enum): """The stages of the lifecycle of an :class:`Instrument`.""" INITIALIZING = auto() - """ - The instrument is being initialized and has not been handed to the user. - It stays in this state if its initialization fails. - """ + """The instrument is being initialized and has not been handed to the user.""" OPEN = auto() """ The instrument has been initialized, registered and handed to the user, who is responsible for closing it. """ CLOSED = auto() - """The instrument has been closed and its attributes stripped.""" + """ + The instrument has been closed and its attributes stripped, or its + initialization failed and closing it has been attempted. + """ # a metaclass that overrides __call__ means that we lose @@ -190,8 +190,8 @@ def __del__(self) -> None: # resources of the instrument have been reused. return try: - # Instruments that failed to initialize have never been handed to - # the user, who could therefore not have closed them. + # Instruments that have not been handed to the user could not have + # been closed by them. if self.__state is _InstrumentState.OPEN: # Like for unclosed files, the instrument is still closed if # the warning is turned into an error, which is then reported @@ -245,6 +245,33 @@ def close(self) -> None: # after stripping the attributes, which would remove the state again self.__state = _InstrumentState.CLOSED + def _close_after_failed_initialization(self, error: BaseException) -> None: + """ + Close the instrument after its initialization raised ``error``. + + This is called by the metaclass, so that the resources that the + instrument acquired before the failure are freed right away. As the + instrument may only be partly initialized, closing it may fail too. + That is noted on ``error`` rather than raised, so that the caller still + sees why the initialization failed. Closing is not retried when the + instrument is garbage collected, since it would most likely fail in the + same way. + """ + if self.__state is _InstrumentState.CLOSED: + # e.g. closed by the subclass itself before raising + return + try: + self.close() + except Exception as close_error: # noqa: BLE001 + # Any failure is added to the error of the initialization, which + # is what the caller needs to see. + error.add_note( + f"Closing the {type(self).__name__} instrument after its failed " + f"initialization also failed: {close_error!r}" + ) + finally: + self.__state = _InstrumentState.CLOSED + @classmethod def close_all( cls, diff --git a/src/qcodes/instrument/instrument_meta.py b/src/qcodes/instrument/instrument_meta.py index 0e907a28b0d..a8d47be106c 100644 --- a/src/qcodes/instrument/instrument_meta.py +++ b/src/qcodes/instrument/instrument_meta.py @@ -7,17 +7,18 @@ class InstrumentMeta(ABCMeta): """ Metaclass used to customize Instrument creation. We want to register the - instance iff __init__ successfully runs, however we can only do this if - we customize the instance initialization process, otherwise there is no - way to run `register_instance` after `__init__` but before the created - instance is returned to the caller. + instance iff __init__ successfully runs, and close it right away if + __init__ fails, however we can only do this if we customize the instance + initialization process, otherwise there is no way to run code after + `__init__` but before the created instance is returned to the caller, or + to get hold of the instance if `__init__` raises. Instead we use the fact that `__new__` and `__init__` are called inside `type.__call__` (https://github.com/python/cpython/blob/main/Objects/typeobject.c#L1077, https://github.com/python/typeshed/blob/master/stdlib/builtins.pyi#L156) - which we will overload to insert our own custom code AFTER `__init__` is - complete. Note this is part of the spec and will work in alternate python + which we will overload to insert our own custom code around `__init__`. + Note this is part of the spec and will work in alternate python implementations like pypy too. We inherit from ABCMeta rather than type for backwards compatibility @@ -30,10 +31,20 @@ class InstrumentMeta(ABCMeta): def __call__(cls, *args: Any, **kwargs: Any) -> Any: """ - Overloads `type.__call__` to add code that runs only if __init__ completes - successfully. + Overloads `type.__call__` to close the instance if `__init__` raises + and to add code that runs only if `__init__` completes successfully. """ - new_inst = super().__call__(*args, **kwargs) + # Create and initialize the instance like type.__call__ does. + new_inst: Any = cls.__new__(cls, *args, **kwargs) + if isinstance(new_inst, cls): + try: + type(new_inst).__init__(new_inst, *args, **kwargs) + except BaseException as error: + # Free the resources that the instance acquired before the + # failure right away, rather than when it is garbage + # collected, since the caller never gets hold of it. + new_inst._close_after_failed_initialization(error) + raise is_abstract = new_inst._is_abstract() if is_abstract: new_inst.close() diff --git a/src/qcodes/instrument/visa.py b/src/qcodes/instrument/visa.py index fb4b05c3e07..f05e47b130c 100644 --- a/src/qcodes/instrument/visa.py +++ b/src/qcodes/instrument/visa.py @@ -271,8 +271,8 @@ def _connect_and_handle_error( try: visa_handle = self._open_resource(address, visalib) except Exception: + # the instrument is closed when its initialization fails self.visa_log.exception(f"Could not connect at {address}") - self.close() raise return visa_handle diff --git a/tests/test_instrument.py b/tests/test_instrument.py index f4979b4c296..d67b47078c0 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -762,14 +762,13 @@ def test_garbage_collecting_unclosed_instrument_closes_it_and_warns() -> None: assert not Instrument.exist("unclosed") -@pytest.mark.usefixtures("close_before_and_after") -def test_garbage_collecting_instrument_that_failed_to_initialize_does_not_warn() -> ( - None -): +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +def test_instrument_that_fails_to_initialize_is_closed_right_away() -> None: """ - An instrument whose initialization failed is still closed when garbage - collected, but without a warning, as it was never handed to the user who - could therefore not have closed it. + An instrument whose initialization failed is closed right away, so that + its resources are freed, rather than when it is garbage collected. It is + neither closed again nor warned about when garbage collected, as it was + never handed to the user who could therefore not have closed it. """ closed: list[str] = [] failing_class = _instrument_class_recording_close(closed, fail_to_initialize=True) @@ -777,6 +776,8 @@ def test_garbage_collecting_instrument_that_failed_to_initialize_does_not_warn() with pytest.raises(RuntimeError, match="Failed to initialize"): failing_class("failing") + assert closed == ["failing"] + with warnings.catch_warnings(record=True) as caught: warnings.simplefilter("always") gc.collect() @@ -785,6 +786,37 @@ def test_garbage_collecting_instrument_that_failed_to_initialize_does_not_warn() assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +def test_failure_to_close_instrument_after_failed_initialization_is_noted() -> None: + """ + If closing an instrument after its initialization failed fails too, the + error of the initialization is raised with a note about the failure to + close it, and closing is not retried when it is garbage collected. + """ + close_attempts: list[str] = [] + + class FailingInstrument(Instrument): + def __init__(self, name: str) -> None: + super().__init__(name) + raise RuntimeError("Failed to initialize") + + def close(self) -> None: + close_attempts.append(self.name) + raise OSError("Failed to close") + + with pytest.raises(RuntimeError, match="Failed to initialize") as exc_info: + FailingInstrument("failing") + + assert exc_info.value.__notes__ == [ + ( + "Closing the FailingInstrument instrument after its failed " + "initialization also failed: OSError('Failed to close')" + ) + ] + gc.collect() + assert close_attempts == ["failing"] + + @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ diff --git a/tests/test_visa.py b/tests/test_visa.py index c146b4de2ee..eaf467be0e7 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -180,6 +180,36 @@ def use_magnet() -> pyvisa.ResourceManager: ) +def test_visa_handle_is_closed_right_away_if_initialization_fails() -> None: + """ + If the initialization of a VISA instrument fails after it has connected, + the VISA handle is closed right away rather than when the instrument is + garbage collected, so that the resource can be opened again. + """ + handles: list[pyvisa.resources.MessageBasedResource] = [] + + class FailsAfterConnecting(VisaInstrument): + def __init__(self, name: str, address: str, **kwargs: Any) -> None: + super().__init__(name, address, **kwargs) + handles.append(self.visa_handle) + raise RuntimeError("Unexpected reply") + + gc_was_enabled = gc.isenabled() + gc.disable() + try: + with pytest.raises(RuntimeError, match="Unexpected reply"): + FailsAfterConnecting( + "x", address="GPIB::1::INSTR", pyvisa_sim_file="AMI430.yaml" + ) + (handle,) = handles + resource_manager = handle.visalib.resource_manager + assert resource_manager is not None + assert resource_manager.list_opened_resources() == [] + finally: + if gc_was_enabled: + gc.enable() + + def test_ask_write_local(mock_visa: MockVisa) -> None: # test normal ask and write behavior mock_visa.state.set(2) From a6d0b696e2e5a49a71e359012180dd173db82248 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 11:02:41 +0100 Subject: [PATCH 05/19] Do not log when closing VISA handles from the finalizer The weakref.finalize callback that closes the VISA handle of an instrument that was not closed runs inside the garbage collector, i.e. at an arbitrary point in time and on any thread, possibly in the middle of other logging, and at interpreter exit, when logging may already have been shut down. Logging there is not safe with all log handlers. Remove the log message, which the ResourceWarning about the unclosed instrument replaces, and with it the instrument name that the finalizer only needed for the message. --- .../+visa_gc_no_logging.underthehood | 4 ++++ src/qcodes/instrument/visa.py | 19 +++++---------- tests/test_visa.py | 23 ++++--------------- 3 files changed, 15 insertions(+), 31 deletions(-) create mode 100644 docs/changes/newsfragments/+visa_gc_no_logging.underthehood diff --git a/docs/changes/newsfragments/+visa_gc_no_logging.underthehood b/docs/changes/newsfragments/+visa_gc_no_logging.underthehood new file mode 100644 index 00000000000..b27dc823bfa --- /dev/null +++ b/docs/changes/newsfragments/+visa_gc_no_logging.underthehood @@ -0,0 +1,4 @@ +``VisaInstrument`` no longer logs when the VISA handle of an instrument that was not closed is closed +as the instrument is garbage collected, since logging from within the garbage collector or during +interpreter shutdown is not safe with all log handlers. The ``ResourceWarning`` about the unclosed +instrument still reports it. diff --git a/src/qcodes/instrument/visa.py b/src/qcodes/instrument/visa.py index f05e47b130c..fba27749f25 100644 --- a/src/qcodes/instrument/visa.py +++ b/src/qcodes/instrument/visa.py @@ -2,7 +2,6 @@ from __future__ import annotations -import logging import warnings from importlib.resources import as_file, files from typing import TYPE_CHECKING, Any, Literal, Self, TypedDict @@ -29,22 +28,16 @@ VISA_LOGGER = f"{InstrumentBase.__module__}.com.visa" -log = logging.getLogger(__name__) - -def _close_visa_handle( - handle: pyvisa.resources.MessageBasedResource, name: str -) -> None: +def _close_visa_handle(handle: pyvisa.resources.MessageBasedResource) -> None: + # This runs inside the garbage collector, i.e. at an arbitrary point in + # time and on any thread, possibly in the middle of other logging, so it + # must not log. It may also run at interpreter exit, when logging may + # already have been shut down. try: if ( handle.session is not None ): # pyvisa sets the session of a handle to None when it is closed - log.info( - "Closing VISA handle to %s as there are no non weak " - "references to the instrument.", - name, - ) - handle.close() except InvalidSession: # the resource is already closed @@ -213,7 +206,7 @@ def __init__( visa_handle = self._connect_and_handle_error(address, visalib) else: visa_handle = self._connect_and_handle_error(address, visalib) - finalize(self, _close_visa_handle, visa_handle, str(self.name)) + finalize(self, _close_visa_handle, visa_handle) self._visa_handle: pyvisa.resources.MessageBasedResource = visa_handle diff --git a/tests/test_visa.py b/tests/test_visa.py index eaf467be0e7..5e51431610a 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -1,5 +1,4 @@ import gc -import logging import re from pathlib import Path from typing import TYPE_CHECKING, Any @@ -142,7 +141,7 @@ def _make_mock_visa() -> "Generator[MockVisa, None, None]": mv.close() -def test_visa_gc_closes_connection(caplog: pytest.LogCaptureFixture) -> None: +def test_visa_gc_closes_connection() -> None: def use_magnet() -> pyvisa.ResourceManager: x = AMIModel430( "x", @@ -158,26 +157,14 @@ def use_magnet() -> pyvisa.ResourceManager: # ensure that any unused instruments that have not been gced are gced before running gc.collect() - caplog.clear() - with caplog.at_level(logging.INFO, logger="qcodes.instrument.visa"): - rm = use_magnet() - with pytest.warns( - ResourceWarning, match="unclosed instrument " - ): - gc.collect() + rm = use_magnet() + with pytest.warns(ResourceWarning, match="unclosed instrument "): + gc.collect() # at this stage the instrument created in use_magnet has gone out of scope - # and we have triggered an explicit gc so the weakref.finalize function - # has been triggered. We test this + # and we have triggered an explicit gc, so the VISA handle should be closed # and the instrument should no longer be in the instrument registry assert len(Instrument._all_instruments) == 0 assert len(rm.list_opened_resources()) == 0 - # the order of the log messages depends on the pyvisa version but regardless - # of which version we should see the message about closing the handle - assert any( - record.message - == "Closing VISA handle to x as there are no non weak references to the instrument." - for record in caplog.records - ) def test_visa_handle_is_closed_right_away_if_initialization_fails() -> None: From 6f39f9daa0c6c03edbfa8a4d9b0f4e475e2702ff Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 11:05:30 +0100 Subject: [PATCH 06/19] Fix stale comment about the logger of IPToVisa The comment referred to the module logger of qcodes.instrument.visa, which IPToVisa no longer uses (it logs its VISA communication to a logger named after VISA_LOGGER, like VisaInstrument) and which has now been removed. --- src/qcodes/instrument/ip_to_visa.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/qcodes/instrument/ip_to_visa.py b/src/qcodes/instrument/ip_to_visa.py index 3548c60fa2e..6c0e73a63f4 100644 --- a/src/qcodes/instrument/ip_to_visa.py +++ b/src/qcodes/instrument/ip_to_visa.py @@ -9,9 +9,8 @@ from .instrument import Instrument from .ip import IPInstrument -# previous to introducing the `InstrumentLoggerAdapter` the IPToVisa instrument -# was logging in the name of the `VisaInstrument`. To maintain that behaviour -# import the `instrument.visa.log` and log to this one. +# Like a VisaInstrument, the IPToVisa instrument logs its VISA communication +# to a logger named after VISA_LOGGER. from .visa import VISA_LOGGER, VisaInstrument # This module provides a class to make an IPInstrument behave like a From 37b06013307d4ffbc49740f241a90d493ae4a0bd Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 11:13:27 +0100 Subject: [PATCH 07/19] Do not log from instruments while the garbage collector closes them The garbage collector runs at an arbitrary point in time and on any thread, possibly in the middle of other logging, where logging is not safe with all log handlers. Yet the close methods of instruments that were not closed log when the garbage collector closes them. Instrument.__del__ now puts the instrument in a new FINALIZING state while closing it, which InstrumentBase exposes to the instrument and its channels and modules as _being_closed_by_garbage_collector. The InstrumentLoggerAdapter, i.e. self.log and self.visa_log, reports logging as disabled in that state, which covers all drivers that log through their instrument loggers without changing them. IPInstrument and SignalHoundUSBSA124B logged through their module loggers, also when closing. They now log through their instrument loggers, which means that their records are emitted by the instrument logger with the name of the instrument. SignalHoundUSBSA124B's public static check_for_error method takes an optional logger for this, which the driver passes through a private _check_for_error method. --- .../newsfragments/+no_logging_in_gc.improved | 7 ++ ...al_hound_instrument_logger.improved_driver | 4 + src/qcodes/instrument/instrument.py | 13 ++++ src/qcodes/instrument/instrument_base.py | 15 ++++ src/qcodes/instrument/ip.py | 21 +++--- .../signal_hound/SignalHound_USB_SA124B.py | 74 +++++++++++-------- src/qcodes/logger/instrument_logger.py | 14 +++- tests/test_instrument.py | 58 +++++++++++++++ 8 files changed, 162 insertions(+), 44 deletions(-) create mode 100644 docs/changes/newsfragments/+no_logging_in_gc.improved create mode 100644 docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver diff --git a/docs/changes/newsfragments/+no_logging_in_gc.improved b/docs/changes/newsfragments/+no_logging_in_gc.improved new file mode 100644 index 00000000000..fbd7b55f02d --- /dev/null +++ b/docs/changes/newsfragments/+no_logging_in_gc.improved @@ -0,0 +1,7 @@ +The instrument loggers (``self.log`` and ``self.visa_log`` of instruments, channels and other +instrument modules) no longer log while the garbage collector closes an instrument that was not +closed, since the garbage collector runs at an arbitrary point in time and on any thread, possibly +in the middle of other logging, where logging is not safe with all log handlers. +``IPInstrument`` now logs through its instrument logger, so that this also applies to it. Its log +records are therefore emitted by the ``qcodes.instrument.instrument_base`` logger with the name of +the instrument, rather than by the ``qcodes.instrument.ip`` logger. diff --git a/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver b/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver new file mode 100644 index 00000000000..f4cc3c26ba7 --- /dev/null +++ b/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver @@ -0,0 +1,4 @@ +The ``SignalHoundUSBSA124B`` driver now logs through its instrument logger, so that it does not log +while the garbage collector closes it. Its log records are therefore emitted by the +``qcodes.instrument.instrument_base`` logger with the name of the instrument, rather than by the +logger of the driver module. ``SignalHoundUSBSA124B.check_for_error`` takes an optional ``logger``. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index e1269dff08e..7a594c21490 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -48,6 +48,12 @@ class _InstrumentState(Enum): The instrument has been closed and its attributes stripped, or its initialization failed and closing it has been attempted. """ + FINALIZING = auto() + """ + The instrument is being closed by the garbage collector, which runs at an + arbitrary point in time and on any thread, possibly in the middle of other + logging, so the instrument must not log. + """ # a metaclass that overrides __call__ means that we lose @@ -207,6 +213,9 @@ def __del__(self) -> None: source=self, ) finally: + # This disables the instrument loggers while closing the + # instrument, see _being_closed_by_garbage_collector. + self.__state = _InstrumentState.FINALIZING try: self.close() except BaseException: # noqa: BLE001, S110 @@ -216,6 +225,10 @@ def __del__(self) -> None: # however that would require careful testing. pass + @property + def _being_closed_by_garbage_collector(self) -> bool: + return self.__state is _InstrumentState.FINALIZING + def close(self) -> None: """ Irreversibly stop this instrument and free its resources. diff --git a/src/qcodes/instrument/instrument_base.py b/src/qcodes/instrument/instrument_base.py index 1947e494f01..b5176c4c6c8 100644 --- a/src/qcodes/instrument/instrument_base.py +++ b/src/qcodes/instrument/instrument_base.py @@ -713,6 +713,21 @@ def root_instrument(self) -> InstrumentBase: return self + @property + def _being_closed_by_garbage_collector(self) -> bool: + """ + Whether the root instrument is being closed by the garbage collector. + + The garbage collector runs at an arbitrary point in time and on any + thread, possibly in the middle of other logging, so the instrument + loggers do not log in the meantime. + """ + root_instrument = self.root_instrument + return ( + root_instrument is not self + and root_instrument._being_closed_by_garbage_collector + ) + @property def name_parts(self) -> list[str]: """ diff --git a/src/qcodes/instrument/ip.py b/src/qcodes/instrument/ip.py index 286b0a6ca26..a238bc16b8c 100644 --- a/src/qcodes/instrument/ip.py +++ b/src/qcodes/instrument/ip.py @@ -2,7 +2,6 @@ from __future__ import annotations -import logging import socket from typing import TYPE_CHECKING, Any @@ -17,8 +16,6 @@ from .instrument_base import InstrumentBaseKWArgs -log = logging.getLogger(__name__) - class IPInstrument(Instrument): r""" @@ -117,13 +114,13 @@ def _connect(self) -> None: self._disconnect() try: - log.info("Opening socket") + self.log.info("Opening socket") self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - log.info(f"Connecting socket to {self._address}:{self._port}") + self.log.info(f"Connecting socket to {self._address}:{self._port}") self._socket.connect((self._address, self._port)) self.set_timeout(self._timeout) except ConnectionRefusedError: - log.warning("Socket connection failed") + self.log.warning("Socket connection failed") if self._socket is not None: self._socket.close() self._socket = None @@ -132,11 +129,11 @@ def _connect(self) -> None: def _disconnect(self) -> None: if self._socket is None: return - log.info("Socket shutdown") + self.log.info("Socket shutdown") self._socket.shutdown(socket.SHUT_RDWR) - log.info("Socket closing") + self.log.info("Socket closing") self._socket.close() - log.info("Socket closed") + self.log.info("Socket closed") self._socket = None def set_timeout(self, timeout: float) -> None: @@ -167,16 +164,16 @@ def _send(self, cmd: str) -> None: if self._socket is None: raise RuntimeError(f"IPInstrument {self.name} is not connected") data = cmd + self._terminator - log.debug(f"Writing {data} to instrument {self.name}") + self.log.debug(f"Writing {data}") self._socket.sendall(data.encode()) def _recv(self) -> str: if self._socket is None: raise RuntimeError(f"IPInstrument {self.name} is not connected") result = self._socket.recv(self._buffer_size) - log.debug(f"Got {result!r} from instrument {self.name}") + self.log.debug(f"Got {result!r}") if result == b"": - log.warning("Got empty response from Socket recv() Connection broken.") + self.log.warning("Got empty response from Socket recv() Connection broken.") return result.decode() def close(self) -> None: diff --git a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py index 8ee870b1e95..4bbca84572d 100644 --- a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py +++ b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py @@ -207,7 +207,7 @@ def __init__( super().__init__(name, **kwargs) self._parameters_synced = False self._trace_updated = False - log.info("Initializing instrument SignalHound USB 124B") + self.log.info("Initializing instrument SignalHound USB 124B") self.dll = ct.CDLL(dll_path or self.dll_path) self._set_ctypes_argtypes() @@ -537,10 +537,10 @@ def sync_parameters(self) -> None: # 1. CenterSpan Configuration center = ct.c_double(self.frequency()) span = ct.c_double(self.span()) - log.info("Setting device CenterSpan configuration.") + self.log.info("Setting device CenterSpan configuration.") err = self.dll.saConfigCenterSpan(self.deviceHandle, center, span) - self.check_for_error(err, "saConfigCenterSpan") + self._check_for_error(err, "saConfigCenterSpan") # 2. Acquisition configuration detectorVals = { @@ -557,29 +557,29 @@ def sync_parameters(self) -> None: scale = scaleVals[self.scale()] err = self.dll.saConfigAcquisition(self.deviceHandle, detector, scale) - self.check_for_error(err, "saConfigAcquisition") + self._check_for_error(err, "saConfigAcquisition") # 3. Reference Level configuration - log.info("Setting device reference level configuration.") + self.log.info("Setting device reference level configuration.") err = self.dll.saConfigLevel(self.deviceHandle, ct.c_double(self.ref_lvl())) - self.check_for_error(err, "saConfigLevel") + self._check_for_error(err, "saConfigLevel") # 4. External Reference configuration if self.external_reference(): external = self.hf.sa_REF_EXTERNAL_IN - log.info("Setting reference frequency from external source.") + self.log.info("Setting reference frequency from external source.") err = self.dll.saSetTimebase(self.deviceHandle, external) - self.check_for_error(err, "saSetTimebase") + self._check_for_error(err, "saSetTimebase") reject_var = ct.c_bool(self.reject_image()) - log.info("Setting device Sweeping configuration.") + self.log.info("Setting device Sweeping configuration.") err = self.dll.saConfigSweepCoupling( self.deviceHandle, ct.c_double(self.rbw()), ct.c_double(self.vbw()), reject_var, ) - self.check_for_error(err, "saConfigSweepCoupling") + self._check_for_error(err, "saConfigSweepCoupling") modeOpts = { "sweeping": self.hf.sa_SWEEPING, @@ -608,7 +608,7 @@ def sync_parameters(self) -> None: """ elif err == saStatus.saBandwidthErr: extrainfo = "RBW is larger than your span. (Sweep Mode)!" - self.check_for_error(err, "saInitiate", extrainfo) + self._check_for_error(err, "saInitiate", extrainfo) self._parameters_synced = True @@ -624,38 +624,38 @@ def openDevice(self) -> None: """ Opens connection to the instrument """ - log.info("Opening Device") + self.log.info("Opening Device") self.deviceHandle = ct.c_int(0) deviceHandlePnt = ct.pointer(self.deviceHandle) err = self.dll.saOpenDevice(deviceHandlePnt) - self.check_for_error(err, "saOpenDevice") + self._check_for_error(err, "saOpenDevice") self.device_type() def close(self) -> None: """ Close connection to the instrument. """ - log.info(f"Closing Device with handle num: {self.deviceHandle.value}") + self.log.info(f"Closing Device with handle num: {self.deviceHandle.value}") try: self.abort() - log.info("Running acquisition aborted.") + self.log.info("Running acquisition aborted.") except Exception: # `check_for_error` raises OSError if the dll reports a failure and # `saStatus` raises ValueError for an unknown status code. As we are # tearing down the instrument we might as well try to continue also on unknown errors. - log.exception("Could not abort acquisition") + self.log.exception("Could not abort acquisition") err = self.dll.saCloseDevice(self.deviceHandle) - self.check_for_error(err, "saCloseDevice") - log.info(f"Closed Device with handle num: {self.deviceHandle.value}") + self._check_for_error(err, "saCloseDevice") + self.log.info(f"Closed Device with handle num: {self.deviceHandle.value}") super().close() def abort(self) -> None: """ Abort any running acquisition. """ - log.info("Stopping acquisition") + self.log.info("Stopping acquisition") err = self.dll.saAbort(self.deviceHandle) extrainfo: str | None = None @@ -665,30 +665,30 @@ def abort(self) -> None: "without ever calling initiate()" ) - self.check_for_error(err, "saAbort", extrainfo) + self._check_for_error(err, "saAbort", extrainfo) def preset(self) -> None: """ Like close but performs a hardware reset before closing the connection. """ - log.warning("Performing hardware-reset of device!") + self.log.warning("Performing hardware-reset of device!") err = self.dll.saPreset(self.deviceHandle) - self.check_for_error(err, "saPreset") + self._check_for_error(err, "saPreset") super().close() def _get_device_type(self) -> str: """ Returns the model string of the Spectrum Analyzer. """ - log.info("Querying device for model information") + self.log.info("Querying device for model information") devType = ct.c_int32(0) devTypePnt = ct.pointer(devType) err = self.dll.saGetDeviceType(self.deviceHandle, devTypePnt) - self.check_for_error(err, "saGetDeviceType") + self._check_for_error(err, "saGetDeviceType") if devType.value == self.hf.saDeviceTypeNone: dev = "No device" @@ -725,7 +725,7 @@ def QuerySweep(self) -> tuple[int, float, float]: ct.pointer(start_freq), ct.pointer(stepsize), ) - self.check_for_error(err, "saQuerySweepInfo") + self._check_for_error(err, "saQuerySweepInfo") return sweep_len.value, start_freq.value, stepsize.value def _get_sweep_data(self) -> npt.NDArray: @@ -752,7 +752,7 @@ def _get_sweep_data(self) -> npt.NDArray: sleep(self.sleep_time.get()) # Added extra sleep for updating issue err = self.dll.saGetSweep_32f(self.deviceHandle, minarr, maxarr) - self.check_for_error(err, "saGetSweep_32f") + self._check_for_error(err, "saGetSweep_32f") data += datamin return data / Navg @@ -785,7 +785,12 @@ def _get_power_at_freq(self) -> float: return max_power @staticmethod - def check_for_error(err: int, source: str, extrainfo: str | None = None) -> None: + def check_for_error( + err: int, + source: str, + extrainfo: str | None = None, + logger: logging.Logger | logging.LoggerAdapter[logging.Logger] = log, + ) -> None: if err != saStatus.saNoError: err_str = saStatus(err).name if err > 0: @@ -795,7 +800,7 @@ def check_for_error(err: int, source: str, extrainfo: str | None = None) -> None ) if extrainfo is not None: msg = msg + f"\n Extra info: {extrainfo}" - log.warning(msg) + logger.warning(msg) else: msg = ( f"During call of {source} the following Error: {err_str} was raised" @@ -807,7 +812,14 @@ def check_for_error(err: int, source: str, extrainfo: str | None = None) -> None msg = f"Call to {source} was successful" if extrainfo is not None: msg = msg + f"\n Extra info: {extrainfo}" - log.info(msg) + logger.info(msg) + + def _check_for_error( + self, err: int, source: str, extrainfo: str | None = None + ) -> None: + # log to the instrument logger, which does not log while the instrument + # is closed by the garbage collector + self.check_for_error(err, source, extrainfo, logger=self.log) def get_idn(self) -> dict[str, str | None]: output: dict[str, str | None] = {} @@ -815,14 +827,14 @@ def get_idn(self) -> dict[str, str | None]: output["model"] = self._get_device_type() serialnumber = ct.c_int32() err = self.dll.saGetSerialNumber(self.deviceHandle, ct.pointer(serialnumber)) - self.check_for_error(err, "saGetSerialNumber") + self._check_for_error(err, "saGetSerialNumber") output["serial"] = str(serialnumber.value) fw_version = (ct.c_char * 17)() # the manual says that this must be at least 16 char # but not clear if that includes a termination zero so # make it 17 just in case err = self.dll.saGetFirmwareString(self.deviceHandle, fw_version) - self.check_for_error(err, "saGetFirmwareString") + self._check_for_error(err, "saGetFirmwareString") output["firmware"] = fw_version.value.decode("ascii") return output diff --git a/src/qcodes/logger/instrument_logger.py b/src/qcodes/logger/instrument_logger.py index 665a8417919..8c337b5370b 100644 --- a/src/qcodes/logger/instrument_logger.py +++ b/src/qcodes/logger/instrument_logger.py @@ -29,7 +29,9 @@ class InstrumentLoggerAdapter(logging.LoggerAdapter[logging.Logger]): Here it is used to add the instruments full name to the log records so that they can be filtered (using the :class:`InstrumentFilter`) by instrument - instance. + instance. It also does not log while the instrument is being closed by + the garbage collector, since that runs at an arbitrary point in time and on + any thread, possibly in the middle of other logging. The context data gets stored in the `extra` dictionary as a property of the Adapter. It is filled by the ``__init__`` method:: @@ -70,6 +72,16 @@ def __init__( ) self.merge_extra = merge_extra + def isEnabledFor(self, level: int) -> bool: + """ + Whether a message of the given level would be logged, which is never + the case while the instrument is being closed by the garbage collector. + """ + instrument = None if self.extra is None else self.extra.get("instrument") + if getattr(instrument, "_being_closed_by_garbage_collector", False): + return False + return super().isEnabledFor(level) + def process( self, msg: str, kwargs: MutableMapping[str, Any] ) -> tuple[str, MutableMapping[str, Any]]: diff --git a/tests/test_instrument.py b/tests/test_instrument.py index d67b47078c0..82272639db6 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -20,6 +20,7 @@ from qcodes.instrument import ( Instrument, InstrumentBase, + InstrumentChannel, InstrumentModule, find_or_create_instrument, ) @@ -841,6 +842,63 @@ def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: new_instrument.close() +class _InstrumentLoggingWhenClosed(Instrument): + """An instrument that logs through itself and its channel when closed.""" + + def __init__(self, name: str) -> None: + super().__init__(name) + self.channel = self.add_submodule("channel", InstrumentChannel(self, "channel")) + + def close(self) -> None: + self.log.info("closing instrument") + self.channel.log.info("closing channel") + super().close() + + +def _close_messages(caplog: pytest.LogCaptureFixture) -> list[str]: + return [ + record.getMessage() + for record in caplog.records + if "closing" in record.getMessage() + ] + + +@pytest.mark.usefixtures("close_before_and_after") +def test_instrument_logs_when_closed_explicitly( + caplog: pytest.LogCaptureFixture, +) -> None: + instrument = _InstrumentLoggingWhenClosed("logging") + + with caplog.at_level(logging.INFO): + instrument.close() + + assert _close_messages(caplog) == [ + "[logging(_InstrumentLoggingWhenClosed)] closing instrument", + "[logging_channel(InstrumentChannel)] closing channel", + ] + + +@pytest.mark.usefixtures("close_before_and_after") +def test_instrument_does_not_log_when_closed_by_garbage_collector( + caplog: pytest.LogCaptureFixture, +) -> None: + """ + The garbage collector runs at an arbitrary point in time and on any + thread, possibly in the middle of other logging, so the loggers of an + instrument and of its channels do not log while it closes the instrument. + """ + _InstrumentLoggingWhenClosed("logging") + + with ( + caplog.at_level(logging.INFO), + pytest.warns(ResourceWarning, match="unclosed instrument"), + ): + gc.collect() + + assert not Instrument.exist("logging") + assert _close_messages(caplog) == [] + + def test_snapshot_and_meta_attrs() -> None: """Test snapshot of InstrumentBase contains _meta_attrs attributes""" instr = InstrumentBase("instr", label="Label") From 97f2ec4439ed0edfd264591fb93864aa52082a82 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 11:43:57 +0100 Subject: [PATCH 08/19] Make closing instruments that are closed or partly initialized safe Closing an instrument strips its attributes, so closing it again raised an AttributeError in drivers whose close methods use their attributes before calling the close method of their base class: IPInstrument, DynaCool, GalilMotionController, KeysightM960x, KeysightM9336A, MiniCircuitsHIDMixin and SignalHoundUSBSA124B. The same applied to closing them after their initialization failed before all their attributes were set, which the metaclass now does right away. Their close methods now only release the resources that exist, using getattr like VisaInstrument does, and Instrument.close returns early if the instrument has already been closed. Its docstring states these requirements for the close methods of subclasses. The drivers that need hardware, vendor libraries or servers to be initialized are tested by closing instances that have not been initialized and therefore have no attributes, like closed instruments. --- .../newsfragments/+close_twice.improved | 2 ++ .../+close_twice.improved_driver | 4 +++ src/qcodes/instrument/instrument.py | 9 +++++- src/qcodes/instrument/ip.py | 5 ++- .../instrument_drivers/Galil/dmc_41x3.py | 5 ++- .../instrument_drivers/Keysight/KtM960x.py | 5 ++- .../instrument_drivers/Keysight/KtMAwg.py | 5 ++- .../Minicircuits/USBHIDMixin.py | 5 ++- .../QuantumDesign/DynaCoolPPMS/DynaCool.py | 25 ++++++++------- .../signal_hound/SignalHound_USB_SA124B.py | 31 ++++++++++-------- tests/drivers/test_close_drivers.py | 32 +++++++++++++++++++ tests/drivers/test_galil_dmc_41x3.py | 2 ++ .../test_minicircuits_usb_hid_mixin.py | 2 ++ tests/test_instrument.py | 14 ++++++++ 14 files changed, 115 insertions(+), 31 deletions(-) create mode 100644 docs/changes/newsfragments/+close_twice.improved create mode 100644 docs/changes/newsfragments/+close_twice.improved_driver create mode 100644 tests/drivers/test_close_drivers.py diff --git a/docs/changes/newsfragments/+close_twice.improved b/docs/changes/newsfragments/+close_twice.improved new file mode 100644 index 00000000000..35e9d4e9fef --- /dev/null +++ b/docs/changes/newsfragments/+close_twice.improved @@ -0,0 +1,2 @@ +Closing an instrument that has already been closed now does nothing. Previously, closing an +``IPInstrument`` a second time raised an ``AttributeError``. diff --git a/docs/changes/newsfragments/+close_twice.improved_driver b/docs/changes/newsfragments/+close_twice.improved_driver new file mode 100644 index 00000000000..c5c042d4186 --- /dev/null +++ b/docs/changes/newsfragments/+close_twice.improved_driver @@ -0,0 +1,4 @@ +Closing a ``DynaCool``, ``GalilMotionController``, ``KeysightM960x``, ``KeysightM9336A``, +``SignalHoundUSBSA124B`` or MiniCircuits USB HID instrument that has already been closed no longer +raises an ``AttributeError``. Closing them after their initialization failed before connecting no +longer fails either. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 7a594c21490..61ee2e4b51a 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -233,9 +233,16 @@ def close(self) -> None: """ Irreversibly stop this instrument and free its resources. + Closing an instrument that has already been closed does nothing. + Subclasses should override this if they have other specific - resources to close. + resources to close, and call this method at the end. Their close + methods must also work if the instrument has already been closed, + i.e. its attributes have been stripped, or if its initialization + failed before all its attributes were set. """ + if self.__state is _InstrumentState.CLOSED: + return if hasattr(self, "connection") and hasattr(self.connection, "close"): self.connection.close() diff --git a/src/qcodes/instrument/ip.py b/src/qcodes/instrument/ip.py index a238bc16b8c..437ead6831a 100644 --- a/src/qcodes/instrument/ip.py +++ b/src/qcodes/instrument/ip.py @@ -178,7 +178,10 @@ def _recv(self) -> str: def close(self) -> None: """Disconnect and irreversibly tear down the instrument.""" - self._disconnect() + # The instrument may already have been closed, in which case its + # attributes have been stripped. + if getattr(self, "_socket", None) is not None: + self._disconnect() super().close() def write_raw(self, cmd: str) -> None: diff --git a/src/qcodes/instrument_drivers/Galil/dmc_41x3.py b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py index b2bbae37b55..342efab8aa5 100644 --- a/src/qcodes/instrument_drivers/Galil/dmc_41x3.py +++ b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py @@ -179,7 +179,10 @@ def close(self) -> None: Close connection to the instrument and irreversibly tear down the instrument. """ - self.g.GClose() + # The instrument may already have been closed, or its initialization may + # have failed before creating the connection. + if getattr(self, "g", None) is not None: + self.g.GClose() super().close() def motion_complete(self, axes: str) -> None: diff --git a/src/qcodes/instrument_drivers/Keysight/KtM960x.py b/src/qcodes/instrument_drivers/Keysight/KtM960x.py index 250345c7347..092e810299b 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtM960x.py +++ b/src/qcodes/instrument_drivers/Keysight/KtM960x.py @@ -295,5 +295,8 @@ def _get_vi_int(self, attr: int) -> int: return int(v.value) def close(self) -> None: - self._dll.KtM960x_close(self._session) + # The instrument may already have been closed, or its initialization may + # have failed before loading the DLL. + if getattr(self, "_dll", None) is not None: + self._dll.KtM960x_close(self._session) super().close() diff --git a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py index 3720be3b605..355c7f62579 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py +++ b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py @@ -405,5 +405,8 @@ def _get_vi_int(self, attr: int, ch: _ch_type = b"") -> int: return int(v.value) def close(self) -> None: - self._dll.KtMAwg_close(self._session) + # The instrument may already have been closed, or its initialization may + # have failed before loading the DLL. + if getattr(self, "_dll", None) is not None: + self._dll.KtMAwg_close(self._session) super().close() diff --git a/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py index 351fa47deff..5293dcdb99d 100644 --- a/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py +++ b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py @@ -166,7 +166,10 @@ def ask_raw(self, cmd: str) -> str: def close(self) -> None: """Disconnect and irreversibly tear down the instrument.""" - self._device.close() + # The instrument may already have been closed, or its initialization may + # have failed before opening the device. + if getattr(self, "_device", None) is not None: + self._device.close() super().close() @classmethod diff --git a/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py b/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py index 1860c14f532..7ae2d13d40e 100644 --- a/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py +++ b/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py @@ -458,15 +458,18 @@ def close(self) -> None: """ Make sure to nicely close the server connection """ - try: - self.log.debug("Closing server connection.") - self.write("CLOSE") - except VisaIOError as e: - self.log.info( - "Could not close connection to server, perhaps the server is down?" - ) - self.log.info( - f"Got the following error from PyVISA: " - f"{e.abbreviation}: {e.description}" - ) + # The instrument may already have been closed, or its initialization may + # have failed before connecting. + if getattr(self, "visa_handle", None) is not None: + try: + self.log.debug("Closing server connection.") + self.write("CLOSE") + except VisaIOError as e: + self.log.info( + "Could not close connection to server, perhaps the server is down?" + ) + self.log.info( + f"Got the following error from PyVISA: " + f"{e.abbreviation}: {e.description}" + ) super().close() diff --git a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py index 4bbca84572d..4bd64703142 100644 --- a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py +++ b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py @@ -635,20 +635,23 @@ def close(self) -> None: """ Close connection to the instrument. """ - self.log.info(f"Closing Device with handle num: {self.deviceHandle.value}") - - try: - self.abort() - self.log.info("Running acquisition aborted.") - except Exception: - # `check_for_error` raises OSError if the dll reports a failure and - # `saStatus` raises ValueError for an unknown status code. As we are - # tearing down the instrument we might as well try to continue also on unknown errors. - self.log.exception("Could not abort acquisition") - - err = self.dll.saCloseDevice(self.deviceHandle) - self._check_for_error(err, "saCloseDevice") - self.log.info(f"Closed Device with handle num: {self.deviceHandle.value}") + # The instrument may already have been closed, or its initialization may + # have failed before opening the device. + if getattr(self, "deviceHandle", None) is not None: + self.log.info(f"Closing Device with handle num: {self.deviceHandle.value}") + + try: + self.abort() + self.log.info("Running acquisition aborted.") + except Exception: + # `check_for_error` raises OSError if the dll reports a failure and + # `saStatus` raises ValueError for an unknown status code. As we are + # tearing down the instrument we might as well try to continue also on unknown errors. + self.log.exception("Could not abort acquisition") + + err = self.dll.saCloseDevice(self.deviceHandle) + self._check_for_error(err, "saCloseDevice") + self.log.info(f"Closed Device with handle num: {self.deviceHandle.value}") super().close() def abort(self) -> None: diff --git a/tests/drivers/test_close_drivers.py b/tests/drivers/test_close_drivers.py new file mode 100644 index 00000000000..84560f24e62 --- /dev/null +++ b/tests/drivers/test_close_drivers.py @@ -0,0 +1,32 @@ +""" +Closing a driver must also work if the instrument has already been closed, in +which case its attributes have been stripped, or if its initialization failed +before all its attributes were set. + +The drivers tested here need hardware, vendor libraries or servers to be +initialized, so they are closed without having been initialized, which leaves +them without any instance attributes, like a closed instrument. +""" + +import pytest + +from qcodes.instrument import Instrument, IPInstrument +from qcodes.instrument_drivers.Keysight.KtM960x import KeysightM960x +from qcodes.instrument_drivers.Keysight.KtMAwg import KeysightM9336A +from qcodes.instrument_drivers.QuantumDesign import DynaCool +from qcodes.instrument_drivers.signal_hound.SignalHound_USB_SA124B import ( + SignalHoundUSBSA124B, +) + + +@pytest.mark.parametrize( + "instrument_class", + [IPInstrument, KeysightM960x, KeysightM9336A, DynaCool, SignalHoundUSBSA124B], +) +def test_close_instrument_without_attributes( + instrument_class: type[Instrument], +) -> None: + instrument = instrument_class.__new__(instrument_class) + + instrument.close() + instrument.close() diff --git a/tests/drivers/test_galil_dmc_41x3.py b/tests/drivers/test_galil_dmc_41x3.py index 3a71e9b1276..9a0c918827b 100644 --- a/tests/drivers/test_galil_dmc_41x3.py +++ b/tests/drivers/test_galil_dmc_41x3.py @@ -62,5 +62,7 @@ def test_close_closes_connection_and_unregisters_instrument( assert not connection.is_open assert not Instrument.exist("galil") + # closing it again does nothing + controller.close() # the name can be reused once the instrument has been closed driver_module.GalilMotionController("galil", address="192.168.1.2").close() diff --git a/tests/drivers/test_minicircuits_usb_hid_mixin.py b/tests/drivers/test_minicircuits_usb_hid_mixin.py index 933809b9a4c..a9a6e12d68f 100644 --- a/tests/drivers/test_minicircuits_usb_hid_mixin.py +++ b/tests/drivers/test_minicircuits_usb_hid_mixin.py @@ -88,5 +88,7 @@ def test_close_closes_device_and_unregisters_instrument(fake_hid: _FakeHid) -> N assert not fake_hid.device.is_open assert not Instrument.exist("minicircuits") + # closing it again does nothing + instrument.close() # the name can be reused once the instrument has been closed mixin_class("minicircuits").close() diff --git a/tests/test_instrument.py b/tests/test_instrument.py index 82272639db6..2e83356e1cd 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -22,6 +22,7 @@ InstrumentBase, InstrumentChannel, InstrumentModule, + IPInstrument, find_or_create_instrument, ) from qcodes.instrument_drivers.mock_instruments import ( @@ -818,6 +819,19 @@ def close(self) -> None: assert close_attempts == ["failing"] +@pytest.mark.usefixtures("close_before_and_after") +def test_closing_ip_instrument_again_does_not_raise() -> None: + # not persistent, so that it does not connect + instrument = IPInstrument( + "ip_instrument", address="127.0.0.1", port=1, persistent=False + ) + + instrument.close() + instrument.close() + + assert not Instrument.exist("ip_instrument") + + @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ From 528a3ad17706129470e4a2070ae4ae4d9a526e24 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 11:46:19 +0100 Subject: [PATCH 09/19] Document how to write close methods of instrument drivers Add a section about closing instruments to the notebook about creating instrument drivers. It lists the situations in which close is called: explicitly, right away when the initialization fails, again after the instrument has been closed, by the garbage collector as a fallback, and at interpreter exit, together with what that means for close, e.g. that it cannot communicate with a VisaInstrument when the garbage collector closes it or at interpreter exit. It then states the rules for writing a close method: release only the resources that exist using getattr, end by calling super().close(), do not rely on communicating with the instrument, log through self.log, and do not implement __del__. An example shows a DLL based driver that opens a session and closes it safely. The logging section now explains that the instrument loggers do not log while the garbage collector closes an instrument, and the section about DLL based instruments refers to the new section. --- .../Creating-Instrument-Drivers.ipynb | 75 ++++++++++++++++++- 1 file changed, 73 insertions(+), 2 deletions(-) diff --git a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb index c6f5faa0734..1a3919e3b21 100644 --- a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb +++ b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb @@ -207,7 +207,9 @@ "```\n", "This way the instrument name will be prepended to the log message and the log messages can be filtered according to the instrument they originate from. See the [example](../logging/logging_example.ipynb) notebook of the logger module for more info.\n", "\n", - "When creating a nested `Instrument`, like e.g. something like the `InstrumentChannel` class, that has a `_parent` property, make sure that this property gets set before calling the `super().__init__` method, so that the full name of the instrument gets resolved correctly for the logging.\n" + "When creating a nested `Instrument`, like e.g. something like the `InstrumentChannel` class, that has a `_parent` property, make sure that this property gets set before calling the `super().__init__` method, so that the full name of the instrument gets resolved correctly for the logging.\n", + "\n", + "The instrument loggers do not log while the garbage collector closes an instrument that was not closed explicitly, since the garbage collector runs at an arbitrary point in time and on any thread, possibly in the middle of other logging, where logging is not safe with all log handlers. This is another reason to log through `self.log` (or `self.visa_log`) in the methods of an instrument, in particular in `close` and in anything that it calls. See [Closing instruments](#Closing-instruments)." ] }, { @@ -465,7 +467,7 @@ "metadata": {}, "source": [ "## DLL-based instruments\n", - "The Alazar cards use their own DLL. C interfaces tend to need a lot of boilerplate, so I'm not going to include it all. The key is: use `Instrument` directly, load the DLL, and have parameters interact with it." + "The Alazar cards use their own DLL. C interfaces tend to need a lot of boilerplate, so I'm not going to include it all. The key is: use `Instrument` directly, load the DLL, and have parameters interact with it. See [Closing instruments](#Closing-instruments) for how to release the resources of the DLL in `close`." ] }, { @@ -836,6 +838,75 @@ "print(\"Executing code after context manager\")" ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Closing instruments\n", + "\n", + "An instrument holds resources, such as a VISA session, a socket, a session or handle of a vendor DLL, or a USB device. Its `close` method releases them. Users are expected to close instruments explicitly, either by calling `close` on each instrument or by calling `Instrument.close_all()`, which QCoDeS also runs at interpreter exit.\n", + "\n", + "As a driver author, you need to know in which situations `close` is called, since it may run on an instrument that is not fully set up or that can no longer communicate:\n", + "\n", + "- **Explicitly, by the user.** This is the normal case, in which the instrument is fully initialized and connected.\n", + "- **When its initialization fails.** If `__init__` raises, QCoDeS closes the partly initialized instrument right away, so that the resources it acquired before the failure are released, and then re-raises the error. Attributes that `__init__` would have set after the failure do not exist. If `close` fails too, that is added as a note to the error of the initialization.\n", + "- **Again, after it has been closed.** Closing an instrument strips it of its attributes. `Instrument.close` then does nothing, but the `close` methods of subclasses run before they call it.\n", + "- **By the garbage collector**, if the user never closed the instrument. This is only a fallback, which also emits a `ResourceWarning`. Instruments refer to themselves through their parameters, so they are only collected when the cyclic garbage collector runs, which may be much later and on any thread. By then, the VISA handle of a `VisaInstrument` has already been closed, so `close` cannot communicate with the instrument. The instrument loggers also do not log in the meantime, since logging from within the garbage collector is not safe with all log handlers.\n", + "- **At interpreter exit**, by `Instrument.close_all`. By then, pyvisa has already closed its connections, so `close` cannot communicate with a `VisaInstrument` here either." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Writing a close method\n", + "\n", + "Only override `close` if your driver holds resources that its base class does not release. `VisaInstrument` closes its VISA handle, so a VISA driver rarely needs to. If you do override it:\n", + "\n", + "- **Release only the resources that exist.** Look up the attributes that hold them with `getattr(self, \"_name\", None)`, like `VisaInstrument.close` does, so that `close` also works on an instrument that has been closed or whose initialization failed before it acquired the resource. Assigning such an attribute only once the resource has been acquired successfully makes this straightforward.\n", + "- **End by calling `super().close()`.** This unregisters the instrument, so that its name can be used again, and strips it. Do not call it first, as the attributes of the instrument are gone afterwards. Handle the errors that you expect while releasing a resource, so that `close` gets to call it.\n", + "- **Do not rely on communicating with the instrument.** Communication in `close`, e.g. to put the instrument into a safe state, only works when the user closes the instrument explicitly. Provide a separate method for anything essential, which users can call before closing the instrument.\n", + "- **Log through `self.log`**, rather than a module level logger (see [Logging](#Logging)), so that nothing is logged when the garbage collector closes the instrument.\n", + "- **Do not implement `__del__`.** `Instrument.__del__` already closes instruments that are garbage collected without having been closed. If a resource must be released even then, independently of `close`, register a `weakref.finalize` callback for it, like `VisaInstrument` does for its VISA handle. The callback must not refer to the instrument, as that would keep the instrument from ever being garbage collected, and it must not log.\n", + "\n", + "The following example opens a session with a vendor DLL in `__init__` and closes it in `close`. The functions of the DLL are made up." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "class DLLInstrumentWithSession(Instrument):\n", + " def __init__(\n", + " self,\n", + " name: str,\n", + " dll_path: str,\n", + " **kwargs: \"Unpack[InstrumentBaseKWArgs]\",\n", + " ):\n", + " super().__init__(name, **kwargs)\n", + " self._dll = ctypes.cdll.LoadLibrary(dll_path)\n", + "\n", + " session = ctypes.c_int(0)\n", + " status = self._dll.OpenSession(ctypes.byref(session))\n", + " if status != 0:\n", + " raise RuntimeError(f\"Could not open a session, error code {status}\")\n", + " # Only assign the session once it has been opened successfully, so that\n", + " # close can tell whether there is a session to close.\n", + " self._session = session\n", + "\n", + " def close(self) -> None:\n", + " # The instrument may already have been closed, in which case its\n", + " # attributes have been stripped, or its initialization may have failed\n", + " # before the session was opened. Only close the session if it exists.\n", + " if getattr(self, \"_session\", None) is not None:\n", + " status = self._dll.CloseSession(self._session)\n", + " if status != 0:\n", + " self.log.warning(\"Could not close the session, error code %s\", status)\n", + " super().close()" + ] + }, { "attachments": {}, "cell_type": "markdown", From ba10cea6537f8214afeeb955b11478d93452ef63 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 13:07:34 +0100 Subject: [PATCH 10/19] Address review of closing instruments Instrument creation: - InstrumentMeta.__call__ now also closes the instrument right away if the check for abstract parameters or registering it fails, e.g. because its name is already in use. Previously, such an instrument kept its resources until it was garbage collected, and a failure to close an instrument with abstract parameters replaced the NotImplementedError. - Like type.__call__, it raises a TypeError if __init__ returns a value, and returns objects that __new__ returns unchanged unless they are actual instances of the class. Instrument state: - Instrument.close keeps the lifecycle state while stripping the attributes, so that the instrument loggers stay disabled throughout if the garbage collector is closing the instrument. - Explain why a KeyboardInterrupt raised while closing an instrument whose initialization failed propagates instead of being noted. Drivers: - IPInstrument closes its socket also if shutting it down fails, e.g. because it is not connected. - DynaCool closes its VISA connection also if telling the server that it closes the connection fails, including because the VISA session has already been closed. - KeysightM960x, KeysightM9336A and SignalHoundUSBSA124B only store their session or device handle once it has been opened, so that they do not try to close a session or device that failed to open. Tests: - Make the test of a failing close after a failed initialization check that the instrument is actually garbage collected, which the traceback of the error prevented. - Disable automatic garbage collection in the tests that expect the ResourceWarning from an explicit collection. - Remove the Galil and Minicircuits attributes of the parent package that importing the drivers with fake vendor libraries sets. Docs: Qualify that instruments are normally only collected by the cyclic garbage collector and that their VISA handle may already be closed, and update the notebook and newsfragments to the behaviour above. --- .../+close_on_failed_init.improved | 3 + .../newsfragments/+close_twice.improved | 6 +- .../+close_twice.improved_driver | 5 +- .../Creating-Instrument-Drivers.ipynb | 4 +- src/qcodes/instrument/instrument.py | 26 ++-- src/qcodes/instrument/instrument_meta.py | 51 +++--- src/qcodes/instrument/ip.py | 7 +- .../instrument_drivers/Keysight/KtM960x.py | 11 +- .../instrument_drivers/Keysight/KtMAwg.py | 11 +- .../QuantumDesign/DynaCoolPPMS/DynaCool.py | 9 ++ .../signal_hound/SignalHound_USB_SA124B.py | 8 +- tests/drivers/test_close_drivers.py | 72 ++++++++- tests/drivers/test_galil_dmc_41x3.py | 5 + .../test_minicircuits_usb_hid_mixin.py | 5 + tests/test_instrument.py | 147 +++++++++++++++++- tests/test_visa.py | 15 +- 16 files changed, 325 insertions(+), 60 deletions(-) diff --git a/docs/changes/newsfragments/+close_on_failed_init.improved b/docs/changes/newsfragments/+close_on_failed_init.improved index 5ee4478dce4..823d0349740 100644 --- a/docs/changes/newsfragments/+close_on_failed_init.improved +++ b/docs/changes/newsfragments/+close_on_failed_init.improved @@ -2,4 +2,7 @@ Instruments whose initialization fails are now closed right away, so that the re acquired before the failure, such as an open VISA connection, are freed immediately rather than when the instrument is garbage collected. Previously, retrying to create an instrument for a resource that can only be opened once could fail until the garbage collector had run. +This also applies to instruments that cannot be registered, e.g. because their name is already in +use, or that have abstract parameters, and to instruments whose ``__init__`` returns a value, which +now raises a ``TypeError`` like for other classes. If closing the instrument fails too, this is added as a note to the error of the initialization. diff --git a/docs/changes/newsfragments/+close_twice.improved b/docs/changes/newsfragments/+close_twice.improved index 35e9d4e9fef..0aeb227f1aa 100644 --- a/docs/changes/newsfragments/+close_twice.improved +++ b/docs/changes/newsfragments/+close_twice.improved @@ -1,2 +1,4 @@ -Closing an instrument that has already been closed now does nothing. Previously, closing an -``IPInstrument`` a second time raised an ``AttributeError``. +``Instrument.close`` now does nothing if the instrument has already been closed; close methods of +subclasses still run before they call it. Closing an ``IPInstrument`` a second time no longer raises +an ``AttributeError``, and closing it now also closes its socket if the socket cannot be shut down, +e.g. because it is not connected. diff --git a/docs/changes/newsfragments/+close_twice.improved_driver b/docs/changes/newsfragments/+close_twice.improved_driver index c5c042d4186..b99ebfb17b5 100644 --- a/docs/changes/newsfragments/+close_twice.improved_driver +++ b/docs/changes/newsfragments/+close_twice.improved_driver @@ -1,4 +1,7 @@ Closing a ``DynaCool``, ``GalilMotionController``, ``KeysightM960x``, ``KeysightM9336A``, ``SignalHoundUSBSA124B`` or MiniCircuits USB HID instrument that has already been closed no longer raises an ``AttributeError``. Closing them after their initialization failed before connecting no -longer fails either. +longer fails either. ``KeysightM960x``, ``KeysightM9336A`` and ``SignalHoundUSBSA124B`` no longer try +to close a session or device that failed to open, and ``DynaCool`` now closes its VISA connection also +if telling the server that it closes the connection fails, e.g. because the VISA session has already +been closed. diff --git a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb index 1a3919e3b21..81bc3eca67e 100644 --- a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb +++ b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb @@ -849,9 +849,9 @@ "As a driver author, you need to know in which situations `close` is called, since it may run on an instrument that is not fully set up or that can no longer communicate:\n", "\n", "- **Explicitly, by the user.** This is the normal case, in which the instrument is fully initialized and connected.\n", - "- **When its initialization fails.** If `__init__` raises, QCoDeS closes the partly initialized instrument right away, so that the resources it acquired before the failure are released, and then re-raises the error. Attributes that `__init__` would have set after the failure do not exist. If `close` fails too, that is added as a note to the error of the initialization.\n", + "- **When its initialization fails.** If `__init__` raises, or the instrument cannot be registered, e.g. because its name is already in use, QCoDeS closes the instrument right away, so that the resources it acquired before the failure are released, and then re-raises the error. Attributes that `__init__` would have set after the failure do not exist. If `close` fails too, that is added as a note to the error of the initialization.\n", "- **Again, after it has been closed.** Closing an instrument strips it of its attributes. `Instrument.close` then does nothing, but the `close` methods of subclasses run before they call it.\n", - "- **By the garbage collector**, if the user never closed the instrument. This is only a fallback, which also emits a `ResourceWarning`. Instruments refer to themselves through their parameters, so they are only collected when the cyclic garbage collector runs, which may be much later and on any thread. By then, the VISA handle of a `VisaInstrument` has already been closed, so `close` cannot communicate with the instrument. The instrument loggers also do not log in the meantime, since logging from within the garbage collector is not safe with all log handlers.\n", + "- **By the garbage collector**, if the user never closed the instrument. This is only a fallback, which also emits a `ResourceWarning`. Instruments refer to themselves through their parameters, so they are normally only collected when the cyclic garbage collector runs, which may be much later and on any thread. By then, the VISA handle of a `VisaInstrument` may already have been closed, so `close` may not be able to communicate with the instrument. The instrument loggers also do not log in the meantime, since logging from within the garbage collector is not safe with all log handlers.\n", "- **At interpreter exit**, by `Instrument.close_all`. By then, pyvisa has already closed its connections, so `close` cannot communicate with a `VisaInstrument` here either." ] }, diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 61ee2e4b51a..364ca5444de 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -183,12 +183,12 @@ def __del__(self) -> None: Do not rely on this: always close instruments explicitly with :meth:`close` (or :meth:`close_all`). As instruments reference - themselves through their parameters, they are only garbage collected - when the cyclic garbage collector runs, which may be much later and on - any thread. At that point, connections that are closed by a finalizer, - such as the VISA handle of a :class:`.VisaInstrument`, have already - been closed, so :meth:`close` can no longer communicate with the - instrument. + themselves through their parameters, they are normally only garbage + collected when the cyclic garbage collector runs, which may be much + later and on any thread. At that point, connections that are closed by + a finalizer, such as the VISA handle of a :class:`.VisaInstrument`, may + already have been closed, so :meth:`close` may no longer be able to + communicate with the instrument. """ if self.__state is _InstrumentState.CLOSED: # Closing it again would rerun the close methods of subclasses at @@ -261,15 +261,18 @@ def close(self) -> None: for channel in channellist: strip_attrs(channel, whitelist=["_short_name", "_parent"]) - strip_attrs(self, whitelist=["_short_name"]) - # after stripping the attributes, which would remove the state again + # Keep the state while stripping the attributes, so that the instrument + # loggers stay disabled if the garbage collector is closing the + # instrument, e.g. when deleting an attribute runs code that logs. + strip_attrs(self, whitelist=["_short_name", "_Instrument__state"]) self.__state = _InstrumentState.CLOSED def _close_after_failed_initialization(self, error: BaseException) -> None: """ Close the instrument after its initialization raised ``error``. - This is called by the metaclass, so that the resources that the + This is called by the metaclass, also if registering the instrument + failed, so that the resources that the instrument acquired before the failure are freed right away. As the instrument may only be partly initialized, closing it may fail too. That is noted on ``error`` rather than raised, so that the caller still @@ -284,7 +287,10 @@ def _close_after_failed_initialization(self, error: BaseException) -> None: self.close() except Exception as close_error: # noqa: BLE001 # Any failure is added to the error of the initialization, which - # is what the caller needs to see. + # is what the caller needs to see. A KeyboardInterrupt or other + # BaseException raised while closing, e.g. by pressing Ctrl+C + # again, propagates instead, with the error of the initialization + # as its context. error.add_note( f"Closing the {type(self).__name__} instrument after its failed " f"initialization also failed: {close_error!r}" diff --git a/src/qcodes/instrument/instrument_meta.py b/src/qcodes/instrument/instrument_meta.py index a8d47be106c..1cd864bcca8 100644 --- a/src/qcodes/instrument/instrument_meta.py +++ b/src/qcodes/instrument/instrument_meta.py @@ -8,10 +8,10 @@ class InstrumentMeta(ABCMeta): """ Metaclass used to customize Instrument creation. We want to register the instance iff __init__ successfully runs, and close it right away if - __init__ fails, however we can only do this if we customize the instance - initialization process, otherwise there is no way to run code after - `__init__` but before the created instance is returned to the caller, or - to get hold of the instance if `__init__` raises. + __init__ or the registration fails, however we can only do this if we + customize the instance initialization process, otherwise there is no way + to run code after `__init__` but before the created instance is returned + to the caller, or to get hold of the instance if `__init__` raises. Instead we use the fact that `__new__` and `__init__` are called inside `type.__call__` @@ -31,27 +31,30 @@ class InstrumentMeta(ABCMeta): def __call__(cls, *args: Any, **kwargs: Any) -> Any: """ - Overloads `type.__call__` to close the instance if `__init__` raises - and to add code that runs only if `__init__` completes successfully. + Overloads `type.__call__` to add code that runs only if `__init__` + completes successfully, and to close the instance if `__init__` or that + code raises. """ # Create and initialize the instance like type.__call__ does. new_inst: Any = cls.__new__(cls, *args, **kwargs) - if isinstance(new_inst, cls): - try: - type(new_inst).__init__(new_inst, *args, **kwargs) - except BaseException as error: - # Free the resources that the instance acquired before the - # failure right away, rather than when it is garbage - # collected, since the caller never gets hold of it. - new_inst._close_after_failed_initialization(error) - raise - is_abstract = new_inst._is_abstract() - if is_abstract: - new_inst.close() - raise NotImplementedError( - f"{new_inst} has un-implemented Abstract Parameter " - f"and cannot be initialized" - ) - - new_inst.record_instance(new_inst) + if not issubclass(type(new_inst), cls): + return new_inst + try: + result = type(new_inst).__init__(new_inst, *args, **kwargs) + if result is not None: + raise TypeError( + f"__init__() should return None, not '{type(result).__name__}'" + ) + if new_inst._is_abstract(): + raise NotImplementedError( + f"{new_inst} has un-implemented Abstract Parameter " + f"and cannot be initialized" + ) + new_inst.record_instance(new_inst) + except BaseException as error: + # Free the resources that the instance acquired before the failure + # right away, rather than when it is garbage collected, since the + # caller never gets hold of it. + new_inst._close_after_failed_initialization(error) + raise return new_inst diff --git a/src/qcodes/instrument/ip.py b/src/qcodes/instrument/ip.py index 437ead6831a..3fef78f000d 100644 --- a/src/qcodes/instrument/ip.py +++ b/src/qcodes/instrument/ip.py @@ -130,7 +130,12 @@ def _disconnect(self) -> None: if self._socket is None: return self.log.info("Socket shutdown") - self._socket.shutdown(socket.SHUT_RDWR) + try: + self._socket.shutdown(socket.SHUT_RDWR) + except OSError: + # e.g. the socket is not connected, because connecting it failed. + # It must be closed in any case. + self.log.debug("Could not shut down socket", exc_info=True) self.log.info("Socket closing") self._socket.close() self.log.info("Socket closed") diff --git a/src/qcodes/instrument_drivers/Keysight/KtM960x.py b/src/qcodes/instrument_drivers/Keysight/KtM960x.py index 092e810299b..e3f7122df2e 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtM960x.py +++ b/src/qcodes/instrument_drivers/Keysight/KtM960x.py @@ -61,7 +61,6 @@ def __init__( self._address = bytes(address, "ascii") self._options = bytes(options, "ascii") - self._session = ctypes.c_int(0) self._dll_loc = dll_path self._dll = ctypes.cdll.LoadLibrary(self._dll_loc) @@ -164,11 +163,15 @@ def __init__( self.connect_message() def _connect(self) -> None: + session = ctypes.c_int(0) status = self._dll.KtM960x_InitWithOptions( - self._address, 1, 1, self._options, ctypes.byref(self._session) + self._address, 1, 1, self._options, ctypes.byref(session) ) if status: raise SystemError(f"connection to device failed! error: {status}") + # Only assign the session once it has been opened successfully, so that + # close does not try to close a session that is not open. + self._session = session def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" @@ -296,7 +299,7 @@ def _get_vi_int(self, attr: int) -> int: def close(self) -> None: # The instrument may already have been closed, or its initialization may - # have failed before loading the DLL. - if getattr(self, "_dll", None) is not None: + # have failed before opening the session. + if getattr(self, "_session", None) is not None: self._dll.KtM960x_close(self._session) super().close() diff --git a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py index 355c7f62579..6ecca00a718 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py +++ b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py @@ -258,7 +258,6 @@ def __init__( self._address = bytes(address, "ascii") self._options = bytes(options, "ascii") - self._session = ctypes.c_int(0) self._dll_loc = dll_path self._dll = ctypes.cdll.LoadLibrary(self._dll_loc) self._channel = ctypes.create_string_buffer(b"Channel1") @@ -299,11 +298,15 @@ def __init__( self.connect_message() def _connect(self) -> None: + session = ctypes.c_int(0) status = self._dll.KtMAwg_InitWithOptions( - self._address, 1, 1, self._options, ctypes.byref(self._session) + self._address, 1, 1, self._options, ctypes.byref(session) ) if status: raise SystemError(f"connection to device failed! error: {status}") + # Only assign the session once it has been opened successfully, so that + # close does not try to close a session that is not open. + self._session = session def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" @@ -406,7 +409,7 @@ def _get_vi_int(self, attr: int, ch: _ch_type = b"") -> int: def close(self) -> None: # The instrument may already have been closed, or its initialization may - # have failed before loading the DLL. - if getattr(self, "_dll", None) is not None: + # have failed before opening the session. + if getattr(self, "_session", None) is not None: self._dll.KtMAwg_close(self._session) super().close() diff --git a/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py b/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py index 7ae2d13d40e..aa3e23f61ea 100644 --- a/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py +++ b/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py @@ -5,6 +5,7 @@ import numpy as np from pyvisa import VisaIOError +from pyvisa.errors import InvalidSession import qcodes.validators as vals from qcodes.instrument import VisaInstrument, VisaInstrumentKWArgs @@ -472,4 +473,12 @@ def close(self) -> None: f"Got the following error from PyVISA: " f"{e.abbreviation}: {e.description}" ) + except InvalidSession: + # e.g. closed by its finalizer if the garbage collector is + # closing the instrument + self.log.debug("The VISA session has already been closed.") + except Exception: + # Closing the server connection is only a courtesy, so the + # instrument is closed below in any case. + self.log.warning("Could not close connection to server", exc_info=True) super().close() diff --git a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py index 4bd64703142..6b31089a307 100644 --- a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py +++ b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py @@ -625,10 +625,12 @@ def openDevice(self) -> None: Opens connection to the instrument """ self.log.info("Opening Device") - self.deviceHandle = ct.c_int(0) - deviceHandlePnt = ct.pointer(self.deviceHandle) - err = self.dll.saOpenDevice(deviceHandlePnt) + device_handle = ct.c_int(0) + err = self.dll.saOpenDevice(ct.pointer(device_handle)) self._check_for_error(err, "saOpenDevice") + # Only assign the handle once the device has been opened successfully, + # so that close does not try to close a device that is not open. + self.deviceHandle = device_handle self.device_type() def close(self) -> None: diff --git a/tests/drivers/test_close_drivers.py b/tests/drivers/test_close_drivers.py index 84560f24e62..d637e8f24bd 100644 --- a/tests/drivers/test_close_drivers.py +++ b/tests/drivers/test_close_drivers.py @@ -5,10 +5,15 @@ The drivers tested here need hardware, vendor libraries or servers to be initialized, so they are closed without having been initialized, which leaves -them without any instance attributes, like a closed instrument. +them without any instance attributes, like a closed instrument, or initialized +with fake vendor libraries that fail to open the device. """ +import ctypes +from unittest import mock + import pytest +from pyvisa.errors import InvalidSession from qcodes.instrument import Instrument, IPInstrument from qcodes.instrument_drivers.Keysight.KtM960x import KeysightM960x @@ -16,6 +21,7 @@ from qcodes.instrument_drivers.QuantumDesign import DynaCool from qcodes.instrument_drivers.signal_hound.SignalHound_USB_SA124B import ( SignalHoundUSBSA124B, + saStatus, ) @@ -30,3 +36,67 @@ def test_close_instrument_without_attributes( instrument.close() instrument.close() + + +def test_dynacool_closes_visa_handle_if_session_is_already_closed() -> None: + """ + DynaCool closes its VISA handle also if saying goodbye to the server fails + because the VISA session has already been closed, e.g. by its finalizer + when the garbage collector closes the instrument. + """ + instrument = DynaCool.__new__(DynaCool) + visa_handle = mock.MagicMock() + instrument._visa_handle = visa_handle + instrument.log = mock.MagicMock() + + with mock.patch.object(DynaCool, "write", side_effect=InvalidSession()): + instrument.close() + + visa_handle.close.assert_called_once() + + +@pytest.mark.parametrize( + ("instrument_class", "function_prefix"), + [ + pytest.param( + KeysightM960x, + "KtM960x", + # unrelated to closing: its Measure parameter does not pass on kwargs + marks=pytest.mark.filterwarnings( + "ignore:Parameter measure_data on instrument keysight does not " + "correctly pass kwargs" + ), + ), + (KeysightM9336A, "KtMAwg"), + ], +) +def test_keysight_does_not_close_session_that_failed_to_open( + instrument_class: type[KeysightM960x | KeysightM9336A], function_prefix: str +) -> None: + dll = mock.MagicMock() + getattr(dll, f"{function_prefix}_InitWithOptions").return_value = 1 + + with ( + mock.patch.object(ctypes.cdll, "LoadLibrary", return_value=dll), + pytest.raises(SystemError, match="connection to device failed") as exc_info, + ): + instrument_class("keysight", address="PXI0::1::INSTR") + + getattr(dll, f"{function_prefix}_close").assert_not_called() + assert not hasattr(exc_info.value, "__notes__") + assert not Instrument.exist("keysight") + + +def test_signal_hound_does_not_close_device_that_failed_to_open() -> None: + dll = mock.MagicMock() + dll.saOpenDevice.return_value = saStatus.saDeviceNotFoundErr + + with ( + mock.patch.object(ctypes, "CDLL", return_value=dll), + pytest.raises(OSError, match="saDeviceNotFoundErr") as exc_info, + ): + SignalHoundUSBSA124B("signal_hound") + + dll.saCloseDevice.assert_not_called() + assert not hasattr(exc_info.value, "__notes__") + assert not Instrument.exist("signal_hound") diff --git a/tests/drivers/test_galil_dmc_41x3.py b/tests/drivers/test_galil_dmc_41x3.py index 9a0c918827b..7741527a247 100644 --- a/tests/drivers/test_galil_dmc_41x3.py +++ b/tests/drivers/test_galil_dmc_41x3.py @@ -11,6 +11,7 @@ import pytest +import qcodes.instrument_drivers from qcodes.instrument import Instrument if TYPE_CHECKING: @@ -43,12 +44,16 @@ def _driver_module_with_fake_gclib( monkeypatch.setitem(sys.modules, "gclib", fake_gclib) for name in ("qcodes.instrument_drivers.Galil", _DRIVER_MODULE): monkeypatch.delitem(sys.modules, name, raising=False) + # importing the package sets it as an attribute of its parent package + monkeypatch.delattr(qcodes.instrument_drivers, "Galil", raising=False) try: yield importlib.import_module(_DRIVER_MODULE) finally: # Do not leave the driver bound to the fake module behind. for name in ("qcodes.instrument_drivers.Galil", _DRIVER_MODULE): sys.modules.pop(name, None) + if hasattr(qcodes.instrument_drivers, "Galil"): + delattr(qcodes.instrument_drivers, "Galil") def test_close_closes_connection_and_unregisters_instrument( diff --git a/tests/drivers/test_minicircuits_usb_hid_mixin.py b/tests/drivers/test_minicircuits_usb_hid_mixin.py index a9a6e12d68f..d186293c76a 100644 --- a/tests/drivers/test_minicircuits_usb_hid_mixin.py +++ b/tests/drivers/test_minicircuits_usb_hid_mixin.py @@ -12,6 +12,7 @@ import pytest +import qcodes.instrument_drivers from qcodes.instrument import Instrument if TYPE_CHECKING: @@ -62,6 +63,8 @@ def _fake_hid(monkeypatch: pytest.MonkeyPatch) -> "Generator[_FakeHid, None, Non monkeypatch.setitem(sys.modules, "clr", types.ModuleType("clr")) for name in _driver_modules(): monkeypatch.delitem(sys.modules, name) + # importing the package sets it as an attribute of its parent package + monkeypatch.delattr(qcodes.instrument_drivers, "Minicircuits", raising=False) try: mixin_module = importlib.import_module(_MIXIN_MODULE) fake_hid = _FakeHid() @@ -77,6 +80,8 @@ def _fake_hid(monkeypatch: pytest.MonkeyPatch) -> "Generator[_FakeHid, None, Non # Do not leave the drivers bound to the fake modules behind. for name in _driver_modules(): sys.modules.pop(name) + if hasattr(qcodes.instrument_drivers, "Minicircuits"): + delattr(qcodes.instrument_drivers, "Minicircuits") def test_close_closes_device_and_unregisters_instrument(fake_hid: _FakeHid) -> None: diff --git a/tests/test_instrument.py b/tests/test_instrument.py index 2e83356e1cd..f0e4fbcdb7f 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -9,6 +9,7 @@ import io import logging import re +import socket import warnings import weakref from typing import TYPE_CHECKING, Any, assert_type @@ -25,6 +26,7 @@ IPInstrument, find_or_create_instrument, ) +from qcodes.instrument import instrument as instrument_module from qcodes.instrument_drivers.mock_instruments import ( DummyBase, DummyChannelInstrument, @@ -35,6 +37,7 @@ ) from qcodes.metadatable import Metadatable from qcodes.parameters import Function, Parameter +from qcodes.utils import strip_attrs if TYPE_CHECKING: from collections.abc import Iterator, Sequence @@ -710,6 +713,7 @@ def test_instrument_label(cls: type[InstrumentBase], request: FixtureRequest) -> assert instrument.label == label +@pytest.mark.usefixtures("automatic_gc_disabled") def test_instrument_without_ref_is_gced() -> None: # When there are no active references to an instrument and it is # gced there should be no live references to the instrument @@ -726,18 +730,24 @@ def use_some_instrument() -> None: def _instrument_class_recording_close( - closed: list[str], *, fail_to_initialize: bool = False + closed: list[str], + *, + fail_to_initialize: bool = False, + created: list[weakref.ref[Instrument]] | None = None, ) -> type[Instrument]: """ Create an instrument class that records the name of each instrument that is closed in ``closed``, also when the instrument has been stripped by an earlier close. If ``fail_to_initialize`` is True, initializing an - instrument of the class raises a ``RuntimeError``. + instrument of the class raises a ``RuntimeError``. If ``created`` is given, + weak references to the created instruments are appended to it. """ class InstrumentRecordingClose(Instrument): def __init__(self, name: str) -> None: super().__init__(name) + if created is not None: + created.append(weakref.ref(self)) if fail_to_initialize: raise RuntimeError("Failed to initialize") @@ -748,7 +758,7 @@ def close(self) -> None: return InstrumentRecordingClose -@pytest.mark.usefixtures("close_before_and_after") +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") def test_garbage_collecting_unclosed_instrument_closes_it_and_warns() -> None: closed: list[str] = [] _instrument_class_recording_close(closed)("unclosed") @@ -773,7 +783,10 @@ def test_instrument_that_fails_to_initialize_is_closed_right_away() -> None: never handed to the user who could therefore not have closed it. """ closed: list[str] = [] - failing_class = _instrument_class_recording_close(closed, fail_to_initialize=True) + created: list[weakref.ref[Instrument]] = [] + failing_class = _instrument_class_recording_close( + closed, fail_to_initialize=True, created=created + ) with pytest.raises(RuntimeError, match="Failed to initialize"): failing_class("failing") @@ -784,6 +797,8 @@ def test_instrument_that_fails_to_initialize_is_closed_right_away() -> None: warnings.simplefilter("always") gc.collect() + (instrument,) = created + assert instrument() is None assert closed == ["failing"] assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] @@ -796,10 +811,12 @@ def test_failure_to_close_instrument_after_failed_initialization_is_noted() -> N close it, and closing is not retried when it is garbage collected. """ close_attempts: list[str] = [] + created: list[weakref.ref[Instrument]] = [] class FailingInstrument(Instrument): def __init__(self, name: str) -> None: super().__init__(name) + created.append(weakref.ref(self)) raise RuntimeError("Failed to initialize") def close(self) -> None: @@ -815,10 +832,111 @@ def close(self) -> None: "initialization also failed: OSError('Failed to close')" ) ] + # the traceback of the error refers to the instrument + del exc_info gc.collect() + + (instrument,) = created + assert instrument() is None assert close_attempts == ["failing"] +@pytest.mark.usefixtures("close_before_and_after") +def test_instrument_whose_init_returns_a_value_raises_and_is_closed() -> None: + closed: list[str] = [] + + class ReturningInstrument(Instrument): + def __init__(self, name: str) -> None: + super().__init__(name) + # deliberately returns a value, which __init__ must not + return 1 # type: ignore[return-value] # noqa: PLE0101 + + def close(self) -> None: + closed.append(self.name) + super().close() + + with pytest.raises(TypeError, match=r"__init__\(\) should return None, not 'int'"): + ReturningInstrument("returning") + + assert closed == ["returning"] + assert not Instrument.exist("returning") + + +def test_instrument_whose_new_returns_another_object_returns_it() -> None: + other = object() + + class OtherInstrument(Instrument): + def __new__(cls, *args: Any, **kwargs: Any) -> Any: + return other + + assert OtherInstrument("other") is other + + +@pytest.mark.usefixtures("close_before_and_after") +def test_instrument_with_name_in_use_is_closed_right_away() -> None: + """ + An instrument that cannot be registered because its name is in use is + closed right away, so that its resources are freed, without unregistering + the instrument that uses the name. + """ + closed: list[str] = [] + instrument_class = _instrument_class_recording_close(closed) + existing_instrument = instrument_class("instr") + + with pytest.raises(KeyError, match="Another instrument has the name: instr"): + instrument_class("instr") + + assert closed == ["instr"] + assert Instrument.find_instrument("instr") is existing_instrument + existing_instrument.close() + + +@pytest.mark.usefixtures("close_before_and_after") +def test_failure_to_close_instrument_with_abstract_parameter_is_noted() -> None: + class AbstractInstrument(Instrument): + def __init__(self, name: str) -> None: + super().__init__(name) + self.add_parameter("voltage", abstract=True) + + def close(self) -> None: + raise OSError("Failed to close") + + with pytest.raises(NotImplementedError, match="Abstract Parameter") as exc_info: + AbstractInstrument("abstract") + + assert exc_info.value.__notes__ == [ + ( + "Closing the AbstractInstrument instrument after its failed " + "initialization also failed: OSError('Failed to close')" + ) + ] + + +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +def test_instrument_stays_closed_by_garbage_collector_while_being_stripped( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """ + Stripping the attributes of an instrument that the garbage collector is + closing keeps its state, so that its loggers stay disabled, e.g. if + deleting an attribute runs code that logs. + """ + observed: list[bool] = [] + + def strip_attrs_and_observe(obj: object, whitelist: Sequence[str] = ()) -> None: + strip_attrs(obj, whitelist=whitelist) + if isinstance(obj, Instrument): + observed.append(obj._being_closed_by_garbage_collector) + + monkeypatch.setattr(instrument_module, "strip_attrs", strip_attrs_and_observe) + Instrument("unclosed") + + with pytest.warns(ResourceWarning, match="unclosed instrument"): + gc.collect() + + assert observed == [True] + + @pytest.mark.usefixtures("close_before_and_after") def test_closing_ip_instrument_again_does_not_raise() -> None: # not persistent, so that it does not connect @@ -832,6 +950,25 @@ def test_closing_ip_instrument_again_does_not_raise() -> None: assert not Instrument.exist("ip_instrument") +@pytest.mark.usefixtures("close_before_and_after") +def test_closing_ip_instrument_closes_socket_that_is_not_connected() -> None: + """ + Closing an IPInstrument closes its socket also if the socket is not + connected, e.g. because connecting it failed, so that it cannot be shut + down. + """ + instrument = IPInstrument( + "ip_instrument", address="127.0.0.1", port=1, persistent=False + ) + unconnected_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + instrument._socket = unconnected_socket + + instrument.close() + + assert unconnected_socket.fileno() == -1 + assert not Instrument.exist("ip_instrument") + + @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ @@ -892,7 +1029,7 @@ def test_instrument_logs_when_closed_explicitly( ] -@pytest.mark.usefixtures("close_before_and_after") +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") def test_instrument_does_not_log_when_closed_by_garbage_collector( caplog: pytest.LogCaptureFixture, ) -> None: diff --git a/tests/test_visa.py b/tests/test_visa.py index 5e51431610a..ad0c53b2eff 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -157,9 +157,18 @@ def use_magnet() -> pyvisa.ResourceManager: # ensure that any unused instruments that have not been gced are gced before running gc.collect() - rm = use_magnet() - with pytest.warns(ResourceWarning, match="unclosed instrument "): - gc.collect() + gc_was_enabled = gc.isenabled() + # so that only the explicit collection below collects the instrument + gc.disable() + try: + rm = use_magnet() + with pytest.warns( + ResourceWarning, match="unclosed instrument " + ): + gc.collect() + finally: + if gc_was_enabled: + gc.enable() # at this stage the instrument created in use_magnet has gone out of scope # and we have triggered an explicit gc, so the VISA handle should be closed # and the instrument should no longer be in the instrument registry From 86a59c57c8297726d16926fc17d3641ff71e96b1 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sat, 14 Nov 2026 13:18:55 +0100 Subject: [PATCH 11/19] Keep the instrument finalizer working late in interpreter shutdown Late in the interpreter shutdown, the globals of modules may have been cleared when an instrument is freed. Instrument.__del__ read the module globals _InstrumentState and warnings outside of its exception handling, so freeing even an instrument that had already been closed would then report an exception ignored in __del__. Bind them as default arguments, like e.g. subprocess.Popen.__del__ does. This could not be reproduced with realistic shutdown scenarios on Python 3.12 or 3.14, so the test simulates the cleared globals. Also note in the newsfragment that subclasses of SignalHoundUSBSA124B that override check_for_error must accept its new logger argument, which the driver now passes when it calls the method itself. --- ...al_hound_instrument_logger.improved_driver | 4 ++- src/qcodes/instrument/instrument.py | 20 +++++++++++---- tests/test_instrument.py | 25 +++++++++++++++++++ 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver b/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver index f4cc3c26ba7..1225473fb70 100644 --- a/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver +++ b/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver @@ -1,4 +1,6 @@ The ``SignalHoundUSBSA124B`` driver now logs through its instrument logger, so that it does not log while the garbage collector closes it. Its log records are therefore emitted by the ``qcodes.instrument.instrument_base`` logger with the name of the instrument, rather than by the -logger of the driver module. ``SignalHoundUSBSA124B.check_for_error`` takes an optional ``logger``. +logger of the driver module. ``SignalHoundUSBSA124B.check_for_error`` takes an optional ``logger``, +which the driver passes when it calls the method itself, so subclasses that override +``check_for_error`` must accept it too. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 364ca5444de..3dc56f5db61 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -16,6 +16,7 @@ from .instrument_meta import InstrumentMeta if TYPE_CHECKING: + from collections.abc import Callable from typing import Self, Unpack from qcodes.logger.instrument_logger import InstrumentLoggerAdapter @@ -175,7 +176,16 @@ def __repr__(self) -> str: """Simplified repr giving just the class and name.""" return f"<{type(self).__name__}: {self.name}>" - def __del__(self) -> None: + def __del__( + self, + # Bound as default arguments, like e.g. subprocess.Popen.__del__ does, + # so that this also works late in the interpreter shutdown, when the + # globals of modules may already have been cleared. + _closed: _InstrumentState = _InstrumentState.CLOSED, + _open: _InstrumentState = _InstrumentState.OPEN, + _finalizing: _InstrumentState = _InstrumentState.FINALIZING, + _warn: Callable[..., None] = warnings.warn, + ) -> None: """ Close the instrument if it is garbage collected without having been closed, so that its resources are freed, and emit a @@ -190,7 +200,7 @@ def __del__(self) -> None: already have been closed, so :meth:`close` may no longer be able to communicate with the instrument. """ - if self.__state is _InstrumentState.CLOSED: + if self.__state is _closed: # Closing it again would rerun the close methods of subclasses at # an arbitrary point in time, possibly after the name or the # resources of the instrument have been reused. @@ -198,11 +208,11 @@ def __del__(self) -> None: try: # Instruments that have not been handed to the user could not have # been closed by them. - if self.__state is _InstrumentState.OPEN: + if self.__state is _open: # Like for unclosed files, the instrument is still closed if # the warning is turned into an error, which is then reported # as an exception ignored in __del__. - warnings.warn( + _warn( f"unclosed instrument {self!r}. Close instruments " "explicitly with close() or Instrument.close_all() " "instead of relying on the garbage collector.", @@ -215,7 +225,7 @@ def __del__(self) -> None: finally: # This disables the instrument loggers while closing the # instrument, see _being_closed_by_garbage_collector. - self.__state = _InstrumentState.FINALIZING + self.__state = _finalizing try: self.close() except BaseException: # noqa: BLE001, S110 diff --git a/tests/test_instrument.py b/tests/test_instrument.py index f0e4fbcdb7f..822b073d74c 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -10,6 +10,7 @@ import logging import re import socket +import sys import warnings import weakref from typing import TYPE_CHECKING, Any, assert_type @@ -969,6 +970,30 @@ def test_closing_ip_instrument_closes_socket_that_is_not_connected() -> None: assert not Instrument.exist("ip_instrument") +@pytest.mark.usefixtures("close_before_and_after") +def test_freeing_closed_instrument_after_module_globals_are_cleared() -> None: + """ + Late in the interpreter shutdown, the globals of modules may have been + cleared when a closed instrument is freed, which must not make its + finalizer fail. + """ + instrument = Instrument("instr") + instrument.close() + instrument_ref = weakref.ref(instrument) + unraisable: list[Any] = [] + + with pytest.MonkeyPatch.context() as monkeypatch: + # simulate the interpreter shutdown clearing the globals of the module + monkeypatch.setattr(instrument_module, "_InstrumentState", None) + monkeypatch.setattr(instrument_module, "warnings", None) + monkeypatch.setattr(sys, "unraisablehook", unraisable.append) + del instrument + gc.collect() + assert instrument_ref() is None + + assert unraisable == [] + + @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ From b7b6d0d006c36c33264283c1256cf74d7f0ef97e Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 07:42:58 +0100 Subject: [PATCH 12/19] Rename newsfragments for PR 8769 --- .../changes/newsfragments/{+gc_close.improved => 8769.improved.1} | 0 .../{+gc_resource_warning.improved => 8769.improved.2} | 0 .../{+close_on_failed_init.improved => 8769.improved.3} | 0 .../newsfragments/{+no_logging_in_gc.improved => 8769.improved.4} | 0 .../newsfragments/{+close_twice.improved => 8769.improved.5} | 0 ..._minicircuits_close.improved_driver => 8769.improved_driver.1} | 0 ...d_instrument_logger.improved_driver => 8769.improved_driver.2} | 0 .../{+close_twice.improved_driver => 8769.improved_driver.3} | 0 .../{+visa_gc_no_logging.underthehood => 8769.underthehood} | 0 9 files changed, 0 insertions(+), 0 deletions(-) rename docs/changes/newsfragments/{+gc_close.improved => 8769.improved.1} (100%) rename docs/changes/newsfragments/{+gc_resource_warning.improved => 8769.improved.2} (100%) rename docs/changes/newsfragments/{+close_on_failed_init.improved => 8769.improved.3} (100%) rename docs/changes/newsfragments/{+no_logging_in_gc.improved => 8769.improved.4} (100%) rename docs/changes/newsfragments/{+close_twice.improved => 8769.improved.5} (100%) rename docs/changes/newsfragments/{+galil_minicircuits_close.improved_driver => 8769.improved_driver.1} (100%) rename docs/changes/newsfragments/{+signal_hound_instrument_logger.improved_driver => 8769.improved_driver.2} (100%) rename docs/changes/newsfragments/{+close_twice.improved_driver => 8769.improved_driver.3} (100%) rename docs/changes/newsfragments/{+visa_gc_no_logging.underthehood => 8769.underthehood} (100%) diff --git a/docs/changes/newsfragments/+gc_close.improved b/docs/changes/newsfragments/8769.improved.1 similarity index 100% rename from docs/changes/newsfragments/+gc_close.improved rename to docs/changes/newsfragments/8769.improved.1 diff --git a/docs/changes/newsfragments/+gc_resource_warning.improved b/docs/changes/newsfragments/8769.improved.2 similarity index 100% rename from docs/changes/newsfragments/+gc_resource_warning.improved rename to docs/changes/newsfragments/8769.improved.2 diff --git a/docs/changes/newsfragments/+close_on_failed_init.improved b/docs/changes/newsfragments/8769.improved.3 similarity index 100% rename from docs/changes/newsfragments/+close_on_failed_init.improved rename to docs/changes/newsfragments/8769.improved.3 diff --git a/docs/changes/newsfragments/+no_logging_in_gc.improved b/docs/changes/newsfragments/8769.improved.4 similarity index 100% rename from docs/changes/newsfragments/+no_logging_in_gc.improved rename to docs/changes/newsfragments/8769.improved.4 diff --git a/docs/changes/newsfragments/+close_twice.improved b/docs/changes/newsfragments/8769.improved.5 similarity index 100% rename from docs/changes/newsfragments/+close_twice.improved rename to docs/changes/newsfragments/8769.improved.5 diff --git a/docs/changes/newsfragments/+galil_minicircuits_close.improved_driver b/docs/changes/newsfragments/8769.improved_driver.1 similarity index 100% rename from docs/changes/newsfragments/+galil_minicircuits_close.improved_driver rename to docs/changes/newsfragments/8769.improved_driver.1 diff --git a/docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver b/docs/changes/newsfragments/8769.improved_driver.2 similarity index 100% rename from docs/changes/newsfragments/+signal_hound_instrument_logger.improved_driver rename to docs/changes/newsfragments/8769.improved_driver.2 diff --git a/docs/changes/newsfragments/+close_twice.improved_driver b/docs/changes/newsfragments/8769.improved_driver.3 similarity index 100% rename from docs/changes/newsfragments/+close_twice.improved_driver rename to docs/changes/newsfragments/8769.improved_driver.3 diff --git a/docs/changes/newsfragments/+visa_gc_no_logging.underthehood b/docs/changes/newsfragments/8769.underthehood similarity index 100% rename from docs/changes/newsfragments/+visa_gc_no_logging.underthehood rename to docs/changes/newsfragments/8769.underthehood From cf7a7eeb8283663331eef83eb2fe6d861ba0d296 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 07:59:49 +0100 Subject: [PATCH 13/19] Assign the session of the Keysight drivers in __init__ _connect now returns the session that it opened instead of assigning it as an attribute, so that all attributes of KeysightM960x and KeysightM9336A are assigned in their __init__. The session is still only assigned once it has been opened successfully. --- src/qcodes/instrument_drivers/Keysight/KtM960x.py | 11 ++++++----- src/qcodes/instrument_drivers/Keysight/KtMAwg.py | 11 ++++++----- 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/src/qcodes/instrument_drivers/Keysight/KtM960x.py b/src/qcodes/instrument_drivers/Keysight/KtM960x.py index e3f7122df2e..039c0df666b 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtM960x.py +++ b/src/qcodes/instrument_drivers/Keysight/KtM960x.py @@ -158,20 +158,21 @@ def __init__( self._get_vi_string, KtM960xDefs.KTM960X_ATTR_INSTRUMENT_MANUFACTURER ) - self._connect() + # Only assign the session once it has been opened successfully, so that + # close does not try to close a session that is not open. + self._session = self._connect() self.connect_message() - def _connect(self) -> None: + def _connect(self) -> ctypes.c_int: + """Open a session with the instrument and return it.""" session = ctypes.c_int(0) status = self._dll.KtM960x_InitWithOptions( self._address, 1, 1, self._options, ctypes.byref(session) ) if status: raise SystemError(f"connection to device failed! error: {status}") - # Only assign the session once it has been opened successfully, so that - # close does not try to close a session that is not open. - self._session = session + return session def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" diff --git a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py index 6ecca00a718..0b5310847bb 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py +++ b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py @@ -293,20 +293,21 @@ def __init__( self._get_vi_string, KtMAwgDefs.KTMAWG_ATTR_INSTRUMENT_MANUFACTURER ) - self._connect() + # Only assign the session once it has been opened successfully, so that + # close does not try to close a session that is not open. + self._session = self._connect() self.connect_message() - def _connect(self) -> None: + def _connect(self) -> ctypes.c_int: + """Open a session with the instrument and return it.""" session = ctypes.c_int(0) status = self._dll.KtMAwg_InitWithOptions( self._address, 1, 1, self._options, ctypes.byref(session) ) if status: raise SystemError(f"connection to device failed! error: {status}") - # Only assign the session once it has been opened successfully, so that - # close does not try to close a session that is not open. - self._session = session + return session def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" From 5e8c1737442ac34bda203a1f7475499eac3689d6 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 08:15:35 +0100 Subject: [PATCH 14/19] Close Keysight sessions opened with a warning status IVI InitWithOptions returns a positive status for warnings, with which the session is opened anyway. KeysightM960x and KeysightM9336A treat any non-zero status as a failure, and since this branch only store the session once it has been opened successfully, such a session was no longer closed. Close it before raising. Which statuses count as failures is unchanged. The test of a session that failed to open now uses a negative error status, and a new test covers a session opened with a warning status. --- .../instrument_drivers/Keysight/KtM960x.py | 4 ++ .../instrument_drivers/Keysight/KtMAwg.py | 4 ++ tests/drivers/test_close_drivers.py | 42 ++++++++++++++++++- 3 files changed, 48 insertions(+), 2 deletions(-) diff --git a/src/qcodes/instrument_drivers/Keysight/KtM960x.py b/src/qcodes/instrument_drivers/Keysight/KtM960x.py index 039c0df666b..985d666be81 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtM960x.py +++ b/src/qcodes/instrument_drivers/Keysight/KtM960x.py @@ -171,6 +171,10 @@ def _connect(self) -> ctypes.c_int: self._address, 1, 1, self._options, ctypes.byref(session) ) if status: + # The session may have been opened anyway, e.g. if the status is a + # (positive) warning. As the instrument is not created, close it. + if session.value: + self._dll.KtM960x_close(session) raise SystemError(f"connection to device failed! error: {status}") return session diff --git a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py index 0b5310847bb..9334351510a 100644 --- a/src/qcodes/instrument_drivers/Keysight/KtMAwg.py +++ b/src/qcodes/instrument_drivers/Keysight/KtMAwg.py @@ -306,6 +306,10 @@ def _connect(self) -> ctypes.c_int: self._address, 1, 1, self._options, ctypes.byref(session) ) if status: + # The session may have been opened anyway, e.g. if the status is a + # (positive) warning. As the instrument is not created, close it. + if session.value: + self._dll.KtMAwg_close(session) raise SystemError(f"connection to device failed! error: {status}") return session diff --git a/tests/drivers/test_close_drivers.py b/tests/drivers/test_close_drivers.py index d637e8f24bd..8dfa1d4fd5b 100644 --- a/tests/drivers/test_close_drivers.py +++ b/tests/drivers/test_close_drivers.py @@ -10,6 +10,7 @@ """ import ctypes +from typing import Any from unittest import mock import pytest @@ -55,7 +56,7 @@ def test_dynacool_closes_visa_handle_if_session_is_already_closed() -> None: visa_handle.close.assert_called_once() -@pytest.mark.parametrize( +_KEYSIGHT_DRIVERS = pytest.mark.parametrize( ("instrument_class", "function_prefix"), [ pytest.param( @@ -70,11 +71,15 @@ def test_dynacool_closes_visa_handle_if_session_is_already_closed() -> None: (KeysightM9336A, "KtMAwg"), ], ) + + +@_KEYSIGHT_DRIVERS def test_keysight_does_not_close_session_that_failed_to_open( instrument_class: type[KeysightM960x | KeysightM9336A], function_prefix: str ) -> None: dll = mock.MagicMock() - getattr(dll, f"{function_prefix}_InitWithOptions").return_value = 1 + # a negative status is an error, with which no session is opened + getattr(dll, f"{function_prefix}_InitWithOptions").return_value = -1 with ( mock.patch.object(ctypes.cdll, "LoadLibrary", return_value=dll), @@ -87,6 +92,39 @@ def test_keysight_does_not_close_session_that_failed_to_open( assert not Instrument.exist("keysight") +@_KEYSIGHT_DRIVERS +def test_keysight_closes_session_opened_with_warning( + instrument_class: type[KeysightM960x | KeysightM9336A], function_prefix: str +) -> None: + """ + A positive status is a warning, with which the session is opened anyway. + The driver still treats it as a failure, so it must close the session. + """ + + def open_session_with_warning( + address: bytes, id_query: int, reset: int, options: bytes, session: Any + ) -> int: + session._obj.value = 42 + return 1 + + dll = mock.MagicMock() + getattr( + dll, f"{function_prefix}_InitWithOptions" + ).side_effect = open_session_with_warning + + with ( + mock.patch.object(ctypes.cdll, "LoadLibrary", return_value=dll), + pytest.raises(SystemError, match="connection to device failed"), + ): + instrument_class("keysight", address="PXI0::1::INSTR") + + close = getattr(dll, f"{function_prefix}_close") + close.assert_called_once() + (session,) = close.call_args.args + assert session.value == 42 + assert not Instrument.exist("keysight") + + def test_signal_hound_does_not_close_device_that_failed_to_open() -> None: dll = mock.MagicMock() dll.saOpenDevice.return_value = saStatus.saDeviceNotFoundErr From 3605038482b358d214a0f7a650ce96de30bf6558 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 08:39:57 +0100 Subject: [PATCH 15/19] Test the drivers changed for closing with fake vendor libraries Add a minimal fake of the Signal Hound sa_api DLL, which implements the functions that the SignalHoundUSBSA124B driver calls based on how the driver uses them, and use it to test initializing, configuring, sweeping, logging through the instrument logger, error and warning statuses, closing (also if aborting fails), presetting and failing to open the device. Previously only the parameter classes of the driver were tested. Also test the successful path of the Keysight drivers with a fake IVI DLL whose functions all succeed, the other errors that DynaCool handles when closing the server connection, and that a failure to close an instrument that the garbage collector collects does not escape its finalizer. This raises the coverage of the lines changed on this branch from 69% to 96%; the remaining lines are logging calls of IPInstrument when connected. --- tests/drivers/test_close_drivers.py | 61 ++-- tests/drivers/test_signal_hound_usb_sa124b.py | 262 +++++++++++++++++- tests/test_instrument.py | 27 ++ 3 files changed, 326 insertions(+), 24 deletions(-) diff --git a/tests/drivers/test_close_drivers.py b/tests/drivers/test_close_drivers.py index 8dfa1d4fd5b..fc6b1947d8e 100644 --- a/tests/drivers/test_close_drivers.py +++ b/tests/drivers/test_close_drivers.py @@ -6,7 +6,8 @@ The drivers tested here need hardware, vendor libraries or servers to be initialized, so they are closed without having been initialized, which leaves them without any instance attributes, like a closed instrument, or initialized -with fake vendor libraries that fail to open the device. +with fake vendor libraries. The SignalHound driver is tested with a fake of its +library in test_signal_hound_usb_sa124b.py. """ import ctypes @@ -14,6 +15,8 @@ from unittest import mock import pytest +from pyvisa import VisaIOError +from pyvisa.constants import StatusCode from pyvisa.errors import InvalidSession from qcodes.instrument import Instrument, IPInstrument @@ -22,7 +25,6 @@ from qcodes.instrument_drivers.QuantumDesign import DynaCool from qcodes.instrument_drivers.signal_hound.SignalHound_USB_SA124B import ( SignalHoundUSBSA124B, - saStatus, ) @@ -39,18 +41,28 @@ def test_close_instrument_without_attributes( instrument.close() -def test_dynacool_closes_visa_handle_if_session_is_already_closed() -> None: +@pytest.mark.parametrize( + "error", + [ + # e.g. closed by its finalizer when the garbage collector closes it + pytest.param(InvalidSession(), id="session already closed"), + pytest.param(VisaIOError(StatusCode.error_timeout), id="server down"), + pytest.param(ValueError("invalid literal"), id="malformed reply"), + ], +) +def test_dynacool_closes_visa_handle_if_closing_server_connection_fails( + error: Exception, +) -> None: """ - DynaCool closes its VISA handle also if saying goodbye to the server fails - because the VISA session has already been closed, e.g. by its finalizer - when the garbage collector closes the instrument. + DynaCool closes its VISA handle also if telling the server that it closes + the connection fails. """ instrument = DynaCool.__new__(DynaCool) visa_handle = mock.MagicMock() instrument._visa_handle = visa_handle instrument.log = mock.MagicMock() - with mock.patch.object(DynaCool, "write", side_effect=InvalidSession()): + with mock.patch.object(DynaCool, "write", side_effect=error): instrument.close() visa_handle.close.assert_called_once() @@ -125,16 +137,29 @@ def open_session_with_warning( assert not Instrument.exist("keysight") -def test_signal_hound_does_not_close_device_that_failed_to_open() -> None: - dll = mock.MagicMock() - dll.saOpenDevice.return_value = saStatus.saDeviceNotFoundErr +class _SucceedingIviDll: + """A fake IVI DLL whose functions all succeed without returning any data.""" - with ( - mock.patch.object(ctypes, "CDLL", return_value=dll), - pytest.raises(OSError, match="saDeviceNotFoundErr") as exc_info, - ): - SignalHoundUSBSA124B("signal_hound") + def __init__(self) -> None: + self._functions: dict[str, mock.MagicMock] = {} - dll.saCloseDevice.assert_not_called() - assert not hasattr(exc_info.value, "__notes__") - assert not Instrument.exist("signal_hound") + def __getattr__(self, name: str) -> mock.MagicMock: + return self._functions.setdefault(name, mock.MagicMock(return_value=0)) + + +@_KEYSIGHT_DRIVERS +def test_keysight_closes_open_session_once( + instrument_class: type[KeysightM960x | KeysightM9336A], function_prefix: str +) -> None: + dll = _SucceedingIviDll() + with mock.patch.object(ctypes.cdll, "LoadLibrary", return_value=dll): + instrument = instrument_class("keysight", address="PXI0::1::INSTR") + + instrument.close() + instrument.close() + + close = getattr(dll, f"{function_prefix}_close") + close.assert_called_once() + (session,) = close.call_args.args + assert isinstance(session, ctypes.c_int) + assert not Instrument.exist("keysight") diff --git a/tests/drivers/test_signal_hound_usb_sa124b.py b/tests/drivers/test_signal_hound_usb_sa124b.py index 34ee5c44996..a6708a0de39 100644 --- a/tests/drivers/test_signal_hound_usb_sa124b.py +++ b/tests/drivers/test_signal_hound_usb_sa124b.py @@ -1,24 +1,274 @@ -"""Tests for the parameter classes of the SignalHound USB SA124B driver. +"""Tests for the SignalHound USB SA124B driver. -The driver itself requires the vendor DLL and a connected device, but the -parameter classes guard against being attached to a different instrument and -that guard can be exercised with any instrument. +The driver requires the vendor DLL and a connected device, so the driver itself +is tested with a minimal fake of the DLL, which implements the functions that +the driver calls, based on how the driver uses them. The parameter classes guard +against being attached to a different instrument and that guard can be +exercised with any instrument. """ -from typing import TYPE_CHECKING +import ctypes +import logging +from typing import TYPE_CHECKING, Any +from unittest import mock +import numpy as np import pytest +from qcodes.instrument import Instrument from qcodes.instrument_drivers.mock_instruments import DummyInstrument from qcodes.instrument_drivers.signal_hound.SignalHound_USB_SA124B import ( + Constants, FrequencySweep, ScaleParameter, + SignalHoundUSBSA124B, SweepTraceParameter, TraceParameter, + saStatus, ) if TYPE_CHECKING: - from collections.abc import Generator + from collections.abc import Callable, Generator + +_DEVICE_HANDLE = 7 +_SWEEP_LENGTH = 5 + + +class _DllFunction: + """ + A function of the fake DLL, which returns the status configured on the + fake for it, and on which the driver can set ctypes argtypes. + """ + + def __init__( + self, dll: "_FakeSignalHoundDll", name: str, function: "Callable[..., None]" + ) -> None: + self._dll = dll + self._name = name + self._function = function + self.argtypes: list[Any] | None = None + + def __call__(self, *args: Any) -> int: + self._dll.calls.append(self._name) + self._function(*args) + return self._dll.statuses.get(self._name, saStatus.saNoError) + + +class _FakeSignalHoundDll: + """ + A fake of the sa_api DLL. Output arguments are passed as ctypes pointers or + arrays, which the fake writes to, like the DLL does. + """ + + def __init__(self) -> None: + self.calls: list[str] = [] + # statuses to return from functions other than saNoError + self.statuses: dict[str, int] = {} + self.closed_handles: list[int] = [] + self._center = 0.0 + self._span = 0.0 + no_op = lambda *args: None # noqa: E731 + functions: dict[str, Callable[..., None]] = { + "saOpenDevice": self._open_device, + "saCloseDevice": self._close_device, + "saGetDeviceType": self._get_device_type, + "saGetSerialNumber": self._get_serial_number, + "saGetFirmwareString": self._get_firmware_string, + "saConfigCenterSpan": self._config_center_span, + "saQuerySweepInfo": self._query_sweep_info, + "saGetSweep_32f": self._get_sweep, + "saConfigAcquisition": no_op, + "saConfigLevel": no_op, + "saSetTimebase": no_op, + "saConfigSweepCoupling": no_op, + "saInitiate": no_op, + "saAbort": no_op, + "saPreset": no_op, + } + for name, function in functions.items(): + setattr(self, name, _DllFunction(self, name, function)) + + def _open_device(self, handle: Any) -> None: + handle.contents.value = _DEVICE_HANDLE + + def _close_device(self, handle: ctypes.c_int) -> None: + self.closed_handles.append(handle.value) + + def _get_device_type(self, handle: ctypes.c_int, device_type: Any) -> None: + device_type.contents.value = Constants.saDeviceTypeSA124B + + def _get_serial_number(self, handle: ctypes.c_int, serial_number: Any) -> None: + serial_number.contents.value = 1234 + + def _get_firmware_string(self, handle: ctypes.c_int, firmware: Any) -> None: + firmware.value = b"Version 3.0.0" + + def _config_center_span( + self, handle: ctypes.c_int, center: ctypes.c_double, span: ctypes.c_double + ) -> None: + self._center = center.value + self._span = span.value + + def _query_sweep_info( + self, handle: ctypes.c_int, sweep_length: Any, start: Any, step: Any + ) -> None: + sweep_length.contents.value = _SWEEP_LENGTH + start.contents.value = self._center - self._span / 2 + step.contents.value = self._span / (_SWEEP_LENGTH - 1) + + def _get_sweep(self, handle: ctypes.c_int, minimum: Any, maximum: Any) -> None: + for index in range(_SWEEP_LENGTH): + minimum[index] = -50.0 + index + maximum[index] = -40.0 + index + + +@pytest.fixture(name="fake_dll") +def _make_fake_dll() -> _FakeSignalHoundDll: + return _FakeSignalHoundDll() + + +@pytest.fixture(name="signal_hound") +def _make_signal_hound( + fake_dll: _FakeSignalHoundDll, +) -> "Generator[SignalHoundUSBSA124B, None, None]": + with mock.patch.object(ctypes, "CDLL", return_value=fake_dll): + instrument = SignalHoundUSBSA124B("signal_hound") + instrument.sleep_time(0) + try: + yield instrument + finally: + instrument.close() + + +def test_initialization_opens_and_configures_device( + signal_hound: SignalHoundUSBSA124B, fake_dll: _FakeSignalHoundDll +) -> None: + assert signal_hound.deviceHandle.value == _DEVICE_HANDLE + assert fake_dll.calls[0] == "saOpenDevice" + assert "saConfigCenterSpan" in fake_dll.calls + assert "saInitiate" in fake_dll.calls + # the external reference is not used by default + assert "saSetTimebase" not in fake_dll.calls + assert signal_hound.get_idn() == { + "vendor": "Signal Hound", + "model": "sa124B", + "serial": "1234", + "firmware": "Version 3.0.0", + } + + +def test_frequency_sweep(signal_hound: SignalHoundUSBSA124B) -> None: + signal_hound.frequency(1e9) + signal_hound.span(1e6) + + frequencies = signal_hound.frequency_axis() + power = signal_hound.freq_sweep() + + np.testing.assert_allclose(frequencies, np.linspace(1e9 - 0.5e6, 1e9 + 0.5e6, 5)) + np.testing.assert_allclose(power, [-50, -49, -48, -47, -46]) + + +def test_configure_with_external_reference( + signal_hound: SignalHoundUSBSA124B, fake_dll: _FakeSignalHoundDll +) -> None: + signal_hound.external_reference(True) + + signal_hound.configure() + + assert "saSetTimebase" in fake_dll.calls + + +def test_logs_through_instrument_logger( + signal_hound: SignalHoundUSBSA124B, + fake_dll: _FakeSignalHoundDll, + caplog: pytest.LogCaptureFixture, +) -> None: + fake_dll.statuses["saConfigLevel"] = saStatus.saNoCorrections + + with caplog.at_level(logging.INFO): + signal_hound.configure() + + records = [ + (record.name, record.levelno, record.getMessage()) for record in caplog.records + ] + prefix = "[signal_hound(SignalHoundUSBSA124B)] " + instrument_logger = "qcodes.instrument.instrument_base" + assert ( + instrument_logger, + logging.INFO, + prefix + "Setting device CenterSpan configuration.", + ) in records + assert ( + instrument_logger, + logging.INFO, + prefix + "Call to saConfigCenterSpan was successful", + ) in records + assert ( + instrument_logger, + logging.WARNING, + prefix + "During call of saConfigLevel the followingWarning: " + "saNoCorrections was raised", + ) in records + + +def test_error_status_raises( + signal_hound: SignalHoundUSBSA124B, fake_dll: _FakeSignalHoundDll +) -> None: + fake_dll.statuses["saQuerySweepInfo"] = saStatus.saInvalidDeviceErr + + with pytest.raises(OSError, match=r"saQuerySweepInfo .* saInvalidDeviceErr"): + signal_hound.QuerySweep() + + +def test_close_aborts_and_closes_device( + signal_hound: SignalHoundUSBSA124B, fake_dll: _FakeSignalHoundDll +) -> None: + signal_hound.close() + signal_hound.close() + + assert fake_dll.calls[-2:] == ["saAbort", "saCloseDevice"] + assert fake_dll.closed_handles == [_DEVICE_HANDLE] + assert not Instrument.exist("signal_hound") + + +def test_close_closes_device_if_abort_fails( + signal_hound: SignalHoundUSBSA124B, + fake_dll: _FakeSignalHoundDll, + caplog: pytest.LogCaptureFixture, +) -> None: + fake_dll.statuses["saAbort"] = saStatus.saInvalidDeviceErr + + with caplog.at_level(logging.ERROR): + signal_hound.close() + + assert fake_dll.closed_handles == [_DEVICE_HANDLE] + assert not Instrument.exist("signal_hound") + assert "Could not abort acquisition" in caplog.text + + +def test_preset_resets_device_and_closes_instrument( + signal_hound: SignalHoundUSBSA124B, fake_dll: _FakeSignalHoundDll +) -> None: + signal_hound.preset() + + assert fake_dll.calls[-1] == "saPreset" + assert not Instrument.exist("signal_hound") + + +def test_device_that_fails_to_open_is_not_closed( + fake_dll: _FakeSignalHoundDll, +) -> None: + fake_dll.statuses["saOpenDevice"] = saStatus.saDeviceNotFoundErr + + with ( + mock.patch.object(ctypes, "CDLL", return_value=fake_dll), + pytest.raises(OSError, match="saDeviceNotFoundErr") as exc_info, + ): + SignalHoundUSBSA124B("signal_hound") + + assert fake_dll.closed_handles == [] + assert not hasattr(exc_info.value, "__notes__") + assert not Instrument.exist("signal_hound") @pytest.fixture(name="not_a_signal_hound") diff --git a/tests/test_instrument.py b/tests/test_instrument.py index 822b073d74c..d0a5b1db941 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -970,6 +970,33 @@ def test_closing_ip_instrument_closes_socket_that_is_not_connected() -> None: assert not Instrument.exist("ip_instrument") +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +def test_failure_to_close_unclosed_instrument_when_garbage_collected_is_ignored( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """ + If closing an instrument that the garbage collector collects fails, the + error does not escape the finalizer, which would report it as an exception + ignored in __del__. + """ + close_attempts: list[str] = [] + + class FailingToCloseInstrument(Instrument): + def close(self) -> None: + close_attempts.append(self.name) + raise OSError("Failed to close") + + unraisable: list[Any] = [] + monkeypatch.setattr(sys, "unraisablehook", unraisable.append) + FailingToCloseInstrument("failing") + + with pytest.warns(ResourceWarning, match="unclosed instrument"): + gc.collect() + + assert close_attempts == ["failing"] + assert unraisable == [] + + @pytest.mark.usefixtures("close_before_and_after") def test_freeing_closed_instrument_after_module_globals_are_cleared() -> None: """ From 5d93da2d86f82a52d05b4935565f82a26ab4c1be Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 08:53:51 +0100 Subject: [PATCH 16/19] Remove the ResourceWarning about unclosed instruments Garbage collection still closes unclosed instruments, but no longer warns about it. The warning made tests fail at random whenever the garbage collector ran before the fixture that closes all instruments, and emitting it from a finalizer had the same problems as logging from one. --- docs/changes/newsfragments/8769.improved.2 | 15 ++--- docs/changes/newsfragments/8769.improved.3 | 15 +++-- docs/changes/newsfragments/8769.improved.4 | 11 ++-- docs/changes/newsfragments/8769.improved.5 | 4 -- docs/changes/newsfragments/8769.underthehood | 3 +- .../Creating-Instrument-Drivers.ipynb | 2 +- src/qcodes/instrument/instrument.py | 55 +++++-------------- tests/test_instrument.py | 55 +++++-------------- tests/test_visa.py | 5 +- 9 files changed, 49 insertions(+), 116 deletions(-) delete mode 100644 docs/changes/newsfragments/8769.improved.5 diff --git a/docs/changes/newsfragments/8769.improved.2 b/docs/changes/newsfragments/8769.improved.2 index 5fca80695f1..823d0349740 100644 --- a/docs/changes/newsfragments/8769.improved.2 +++ b/docs/changes/newsfragments/8769.improved.2 @@ -1,7 +1,8 @@ -Instruments that are garbage collected without having been closed now emit a ``ResourceWarning`` -(like unclosed files) when the garbage collector closes them. Garbage collection only closes -instruments on a best effort basis, at an arbitrary later point in time, so instruments should -always be closed explicitly, e.g. with ``close`` or ``Instrument.close_all``. -Python hides ``ResourceWarning`` by default, but it is shown e.g. by pytest and in Python's -development mode. Test suites that turn warnings into errors report it as an exception ignored in -``Instrument.__del__``. Instruments that fail to initialize are still closed without a warning. +Instruments whose initialization fails are now closed right away, so that the resources they +acquired before the failure, such as an open VISA connection, are freed immediately rather than +when the instrument is garbage collected. Previously, retrying to create an instrument for a +resource that can only be opened once could fail until the garbage collector had run. +This also applies to instruments that cannot be registered, e.g. because their name is already in +use, or that have abstract parameters, and to instruments whose ``__init__`` returns a value, which +now raises a ``TypeError`` like for other classes. +If closing the instrument fails too, this is added as a note to the error of the initialization. diff --git a/docs/changes/newsfragments/8769.improved.3 b/docs/changes/newsfragments/8769.improved.3 index 823d0349740..fbd7b55f02d 100644 --- a/docs/changes/newsfragments/8769.improved.3 +++ b/docs/changes/newsfragments/8769.improved.3 @@ -1,8 +1,7 @@ -Instruments whose initialization fails are now closed right away, so that the resources they -acquired before the failure, such as an open VISA connection, are freed immediately rather than -when the instrument is garbage collected. Previously, retrying to create an instrument for a -resource that can only be opened once could fail until the garbage collector had run. -This also applies to instruments that cannot be registered, e.g. because their name is already in -use, or that have abstract parameters, and to instruments whose ``__init__`` returns a value, which -now raises a ``TypeError`` like for other classes. -If closing the instrument fails too, this is added as a note to the error of the initialization. +The instrument loggers (``self.log`` and ``self.visa_log`` of instruments, channels and other +instrument modules) no longer log while the garbage collector closes an instrument that was not +closed, since the garbage collector runs at an arbitrary point in time and on any thread, possibly +in the middle of other logging, where logging is not safe with all log handlers. +``IPInstrument`` now logs through its instrument logger, so that this also applies to it. Its log +records are therefore emitted by the ``qcodes.instrument.instrument_base`` logger with the name of +the instrument, rather than by the ``qcodes.instrument.ip`` logger. diff --git a/docs/changes/newsfragments/8769.improved.4 b/docs/changes/newsfragments/8769.improved.4 index fbd7b55f02d..0aeb227f1aa 100644 --- a/docs/changes/newsfragments/8769.improved.4 +++ b/docs/changes/newsfragments/8769.improved.4 @@ -1,7 +1,4 @@ -The instrument loggers (``self.log`` and ``self.visa_log`` of instruments, channels and other -instrument modules) no longer log while the garbage collector closes an instrument that was not -closed, since the garbage collector runs at an arbitrary point in time and on any thread, possibly -in the middle of other logging, where logging is not safe with all log handlers. -``IPInstrument`` now logs through its instrument logger, so that this also applies to it. Its log -records are therefore emitted by the ``qcodes.instrument.instrument_base`` logger with the name of -the instrument, rather than by the ``qcodes.instrument.ip`` logger. +``Instrument.close`` now does nothing if the instrument has already been closed; close methods of +subclasses still run before they call it. Closing an ``IPInstrument`` a second time no longer raises +an ``AttributeError``, and closing it now also closes its socket if the socket cannot be shut down, +e.g. because it is not connected. diff --git a/docs/changes/newsfragments/8769.improved.5 b/docs/changes/newsfragments/8769.improved.5 deleted file mode 100644 index 0aeb227f1aa..00000000000 --- a/docs/changes/newsfragments/8769.improved.5 +++ /dev/null @@ -1,4 +0,0 @@ -``Instrument.close`` now does nothing if the instrument has already been closed; close methods of -subclasses still run before they call it. Closing an ``IPInstrument`` a second time no longer raises -an ``AttributeError``, and closing it now also closes its socket if the socket cannot be shut down, -e.g. because it is not connected. diff --git a/docs/changes/newsfragments/8769.underthehood b/docs/changes/newsfragments/8769.underthehood index b27dc823bfa..91085a1e2a0 100644 --- a/docs/changes/newsfragments/8769.underthehood +++ b/docs/changes/newsfragments/8769.underthehood @@ -1,4 +1,3 @@ ``VisaInstrument`` no longer logs when the VISA handle of an instrument that was not closed is closed as the instrument is garbage collected, since logging from within the garbage collector or during -interpreter shutdown is not safe with all log handlers. The ``ResourceWarning`` about the unclosed -instrument still reports it. +interpreter shutdown is not safe with all log handlers. diff --git a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb index 81bc3eca67e..fb42cea6de6 100644 --- a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb +++ b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb @@ -851,7 +851,7 @@ "- **Explicitly, by the user.** This is the normal case, in which the instrument is fully initialized and connected.\n", "- **When its initialization fails.** If `__init__` raises, or the instrument cannot be registered, e.g. because its name is already in use, QCoDeS closes the instrument right away, so that the resources it acquired before the failure are released, and then re-raises the error. Attributes that `__init__` would have set after the failure do not exist. If `close` fails too, that is added as a note to the error of the initialization.\n", "- **Again, after it has been closed.** Closing an instrument strips it of its attributes. `Instrument.close` then does nothing, but the `close` methods of subclasses run before they call it.\n", - "- **By the garbage collector**, if the user never closed the instrument. This is only a fallback, which also emits a `ResourceWarning`. Instruments refer to themselves through their parameters, so they are normally only collected when the cyclic garbage collector runs, which may be much later and on any thread. By then, the VISA handle of a `VisaInstrument` may already have been closed, so `close` may not be able to communicate with the instrument. The instrument loggers also do not log in the meantime, since logging from within the garbage collector is not safe with all log handlers.\n", + "- **By the garbage collector**, if the user never closed the instrument. This is only a fallback. Instruments refer to themselves through their parameters, so they are normally only collected when the cyclic garbage collector runs, which may be much later and on any thread. By then, the VISA handle of a `VisaInstrument` may already have been closed, so `close` may not be able to communicate with the instrument. The instrument loggers also do not log in the meantime, since logging from within the garbage collector is not safe with all log handlers.\n", "- **At interpreter exit**, by `Instrument.close_all`. By then, pyvisa has already closed its connections, so `close` cannot communicate with a `VisaInstrument` here either." ] }, diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 3dc56f5db61..21584f6e774 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -4,7 +4,6 @@ import logging import time -import warnings import weakref from enum import Enum, auto from typing import TYPE_CHECKING, Any, ClassVar, Protocol, overload @@ -16,7 +15,6 @@ from .instrument_meta import InstrumentMeta if TYPE_CHECKING: - from collections.abc import Callable from typing import Self, Unpack from qcodes.logger.instrument_logger import InstrumentLoggerAdapter @@ -37,13 +35,8 @@ def write(self, cmd: str) -> None: ... class _InstrumentState(Enum): """The stages of the lifecycle of an :class:`Instrument`.""" - INITIALIZING = auto() - """The instrument is being initialized and has not been handed to the user.""" OPEN = auto() - """ - The instrument has been initialized, registered and handed to the user, - who is responsible for closing it. - """ + """The instrument is being initialized or has been initialized.""" CLOSED = auto() """ The instrument has been closed and its attributes stripped, or its @@ -89,7 +82,7 @@ class Instrument(InstrumentBase, metaclass=instrument_meta_class): _type: type[Instrument] | None = None _instances: ClassVar[weakref.WeakSet[Instrument]] = weakref.WeakSet() # Name mangled so that it cannot clash with attributes of subclasses. - __state: _InstrumentState = _InstrumentState.INITIALIZING + __state: _InstrumentState = _InstrumentState.OPEN def __init__(self, name: str, **kwargs: Unpack[InstrumentBaseKWArgs]) -> None: self._t0 = time.time() @@ -182,14 +175,11 @@ def __del__( # so that this also works late in the interpreter shutdown, when the # globals of modules may already have been cleared. _closed: _InstrumentState = _InstrumentState.CLOSED, - _open: _InstrumentState = _InstrumentState.OPEN, _finalizing: _InstrumentState = _InstrumentState.FINALIZING, - _warn: Callable[..., None] = warnings.warn, ) -> None: """ Close the instrument if it is garbage collected without having been - closed, so that its resources are freed, and emit a - :class:`ResourceWarning` about it. + closed, so that its resources are freed. Do not rely on this: always close instruments explicitly with :meth:`close` (or :meth:`close_all`). As instruments reference @@ -205,35 +195,17 @@ def __del__( # an arbitrary point in time, possibly after the name or the # resources of the instrument have been reused. return + # This disables the instrument loggers while closing the instrument, see + # _being_closed_by_garbage_collector. + self.__state = _finalizing try: - # Instruments that have not been handed to the user could not have - # been closed by them. - if self.__state is _open: - # Like for unclosed files, the instrument is still closed if - # the warning is turned into an error, which is then reported - # as an exception ignored in __del__. - _warn( - f"unclosed instrument {self!r}. Close instruments " - "explicitly with close() or Instrument.close_all() " - "instead of relying on the garbage collector.", - ResourceWarning, - # Point at this method rather than at whatever code - # happened to trigger the garbage collection. - stacklevel=1, - source=self, - ) - finally: - # This disables the instrument loggers while closing the - # instrument, see _being_closed_by_garbage_collector. - self.__state = _finalizing - try: - self.close() - except BaseException: # noqa: BLE001, S110 - # we want to avoid __del__ raising any exceptions - # it might be possible to avoid this see - # https://docs.python.org/3/reference/datamodel.html#object.__del - # however that would require careful testing. - pass + self.close() + except BaseException: # noqa: BLE001, S110 + # we want to avoid __del__ raising any exceptions + # it might be possible to avoid this see + # https://docs.python.org/3/reference/datamodel.html#object.__del + # however that would require careful testing. + pass @property def _being_closed_by_garbage_collector(self) -> bool: @@ -382,7 +354,6 @@ def record_instance(cls, instance: Instrument) -> None: cls._type = cls cls._instances = weakref.WeakSet() cls._instances.add(instance) - instance.__state = _InstrumentState.OPEN @classmethod def instances(cls: type[Self]) -> list[Self]: diff --git a/tests/test_instrument.py b/tests/test_instrument.py index d0a5b1db941..daf8d63a0d7 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -11,7 +11,6 @@ import re import socket import sys -import warnings import weakref from typing import TYPE_CHECKING, Any, assert_type from weakref import WeakValueDictionary @@ -632,10 +631,7 @@ def test_close_when_gc_finalizes_instrument_during_registry_iteration( assert not Instrument.exist("dummy") DummyInstrument(name="dummy", gates=["dac1"]).close() - with pytest.warns( - ResourceWarning, match="unclosed instrument " - ): - gc.collect() + gc.collect() assert len(Instrument._all_instruments) == 0 @@ -653,10 +649,7 @@ def test_close_all_when_gc_finalizes_instrument_during_registry_iteration( _leak_instrument("leaked") parabola = MockParabola("parabola") - with pytest.warns( - ResourceWarning, match="unclosed instrument " - ): - Instrument.close_all() + Instrument.close_all() assert registry.collected_garbage assert not Instrument.is_valid(dummy) @@ -725,8 +718,7 @@ def use_some_instrument() -> None: assert len(Instrument._all_instruments) == 0 use_some_instrument() - with pytest.warns(ResourceWarning, match="unclosed instrument"): - gc.collect() + gc.collect() assert len(Instrument._all_instruments) == 0 @@ -760,16 +752,11 @@ def close(self) -> None: @pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") -def test_garbage_collecting_unclosed_instrument_closes_it_and_warns() -> None: +def test_garbage_collecting_unclosed_instrument_closes_it() -> None: closed: list[str] = [] _instrument_class_recording_close(closed)("unclosed") - with pytest.warns( - ResourceWarning, - match=r"unclosed instrument \. " - r"Close instruments explicitly", - ): - gc.collect() + gc.collect() assert closed == ["unclosed"] assert not Instrument.exist("unclosed") @@ -780,8 +767,7 @@ def test_instrument_that_fails_to_initialize_is_closed_right_away() -> None: """ An instrument whose initialization failed is closed right away, so that its resources are freed, rather than when it is garbage collected. It is - neither closed again nor warned about when garbage collected, as it was - never handed to the user who could therefore not have closed it. + not closed again when garbage collected. """ closed: list[str] = [] created: list[weakref.ref[Instrument]] = [] @@ -794,14 +780,11 @@ def test_instrument_that_fails_to_initialize_is_closed_right_away() -> None: assert closed == ["failing"] - with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") - gc.collect() + gc.collect() (instrument,) = created assert instrument() is None assert closed == ["failing"] - assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] @pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") @@ -932,8 +915,7 @@ def strip_attrs_and_observe(obj: object, whitelist: Sequence[str] = ()) -> None: monkeypatch.setattr(instrument_module, "strip_attrs", strip_attrs_and_observe) Instrument("unclosed") - with pytest.warns(ResourceWarning, match="unclosed instrument"): - gc.collect() + gc.collect() assert observed == [True] @@ -990,8 +972,7 @@ def close(self) -> None: monkeypatch.setattr(sys, "unraisablehook", unraisable.append) FailingToCloseInstrument("failing") - with pytest.warns(ResourceWarning, match="unclosed instrument"): - gc.collect() + gc.collect() assert close_attempts == ["failing"] assert unraisable == [] @@ -1012,7 +993,6 @@ def test_freeing_closed_instrument_after_module_globals_are_cleared() -> None: with pytest.MonkeyPatch.context() as monkeypatch: # simulate the interpreter shutdown clearing the globals of the module monkeypatch.setattr(instrument_module, "_InstrumentState", None) - monkeypatch.setattr(instrument_module, "warnings", None) monkeypatch.setattr(sys, "unraisablehook", unraisable.append) del instrument gc.collect() @@ -1024,9 +1004,8 @@ def test_freeing_closed_instrument_after_module_globals_are_cleared() -> None: @pytest.mark.usefixtures("close_before_and_after") def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: """ - An instrument that has been closed explicitly is neither closed again nor - warned about when garbage collected, which may happen after its name has - been reused. + An instrument that has been closed explicitly is not closed again when + garbage collected, which may happen after its name has been reused. """ closed: list[str] = [] instrument_class = _instrument_class_recording_close(closed) @@ -1034,13 +1013,10 @@ def test_garbage_collecting_closed_instrument_does_not_close_it_again() -> None: old_instrument.close() new_instrument = instrument_class("instr") - with warnings.catch_warnings(record=True) as caught: - warnings.simplefilter("always") - del old_instrument - gc.collect() + del old_instrument + gc.collect() assert closed == ["instr"] - assert [w for w in caught if issubclass(w.category, ResourceWarning)] == [] assert Instrument.find_instrument("instr") is new_instrument new_instrument.close() @@ -1092,10 +1068,7 @@ def test_instrument_does_not_log_when_closed_by_garbage_collector( """ _InstrumentLoggingWhenClosed("logging") - with ( - caplog.at_level(logging.INFO), - pytest.warns(ResourceWarning, match="unclosed instrument"), - ): + with caplog.at_level(logging.INFO): gc.collect() assert not Instrument.exist("logging") diff --git a/tests/test_visa.py b/tests/test_visa.py index ad0c53b2eff..32e48dccb7c 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -162,10 +162,7 @@ def use_magnet() -> pyvisa.ResourceManager: gc.disable() try: rm = use_magnet() - with pytest.warns( - ResourceWarning, match="unclosed instrument " - ): - gc.collect() + gc.collect() finally: if gc_was_enabled: gc.enable() From 11408290b04406d2ca64117d5adbb8a0a446ca55 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 09:22:11 +0100 Subject: [PATCH 17/19] Make SignalHoundUSBSA124B.check_for_error log through the instrument logger Make it an instance method rather than passing the logger to a static method through a private wrapper, so that overrides keep working unchanged. --- .../newsfragments/8769.improved_driver.2 | 5 +- .../signal_hound/SignalHound_USB_SA124B.py | 50 +++++++------------ 2 files changed, 20 insertions(+), 35 deletions(-) diff --git a/docs/changes/newsfragments/8769.improved_driver.2 b/docs/changes/newsfragments/8769.improved_driver.2 index 1225473fb70..4fc8926cc33 100644 --- a/docs/changes/newsfragments/8769.improved_driver.2 +++ b/docs/changes/newsfragments/8769.improved_driver.2 @@ -1,6 +1,5 @@ The ``SignalHoundUSBSA124B`` driver now logs through its instrument logger, so that it does not log while the garbage collector closes it. Its log records are therefore emitted by the ``qcodes.instrument.instrument_base`` logger with the name of the instrument, rather than by the -logger of the driver module. ``SignalHoundUSBSA124B.check_for_error`` takes an optional ``logger``, -which the driver passes when it calls the method itself, so subclasses that override -``check_for_error`` must accept it too. +logger of the driver module. ``SignalHoundUSBSA124B.check_for_error`` is therefore no longer a +static method, so it can no longer be called on the class without an instance. diff --git a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py index 6b31089a307..95fc8a22fbf 100644 --- a/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py +++ b/src/qcodes/instrument_drivers/signal_hound/SignalHound_USB_SA124B.py @@ -1,5 +1,4 @@ import ctypes as ct -import logging from enum import IntEnum from time import sleep from typing import TYPE_CHECKING, Any, Self @@ -14,8 +13,6 @@ if TYPE_CHECKING: from typing import Unpack -log = logging.getLogger(__name__) - class TraceParameter(Parameter): """ @@ -540,7 +537,7 @@ def sync_parameters(self) -> None: self.log.info("Setting device CenterSpan configuration.") err = self.dll.saConfigCenterSpan(self.deviceHandle, center, span) - self._check_for_error(err, "saConfigCenterSpan") + self.check_for_error(err, "saConfigCenterSpan") # 2. Acquisition configuration detectorVals = { @@ -557,19 +554,19 @@ def sync_parameters(self) -> None: scale = scaleVals[self.scale()] err = self.dll.saConfigAcquisition(self.deviceHandle, detector, scale) - self._check_for_error(err, "saConfigAcquisition") + self.check_for_error(err, "saConfigAcquisition") # 3. Reference Level configuration self.log.info("Setting device reference level configuration.") err = self.dll.saConfigLevel(self.deviceHandle, ct.c_double(self.ref_lvl())) - self._check_for_error(err, "saConfigLevel") + self.check_for_error(err, "saConfigLevel") # 4. External Reference configuration if self.external_reference(): external = self.hf.sa_REF_EXTERNAL_IN self.log.info("Setting reference frequency from external source.") err = self.dll.saSetTimebase(self.deviceHandle, external) - self._check_for_error(err, "saSetTimebase") + self.check_for_error(err, "saSetTimebase") reject_var = ct.c_bool(self.reject_image()) self.log.info("Setting device Sweeping configuration.") @@ -579,7 +576,7 @@ def sync_parameters(self) -> None: ct.c_double(self.vbw()), reject_var, ) - self._check_for_error(err, "saConfigSweepCoupling") + self.check_for_error(err, "saConfigSweepCoupling") modeOpts = { "sweeping": self.hf.sa_SWEEPING, @@ -608,7 +605,7 @@ def sync_parameters(self) -> None: """ elif err == saStatus.saBandwidthErr: extrainfo = "RBW is larger than your span. (Sweep Mode)!" - self._check_for_error(err, "saInitiate", extrainfo) + self.check_for_error(err, "saInitiate", extrainfo) self._parameters_synced = True @@ -627,7 +624,7 @@ def openDevice(self) -> None: self.log.info("Opening Device") device_handle = ct.c_int(0) err = self.dll.saOpenDevice(ct.pointer(device_handle)) - self._check_for_error(err, "saOpenDevice") + self.check_for_error(err, "saOpenDevice") # Only assign the handle once the device has been opened successfully, # so that close does not try to close a device that is not open. self.deviceHandle = device_handle @@ -652,7 +649,7 @@ def close(self) -> None: self.log.exception("Could not abort acquisition") err = self.dll.saCloseDevice(self.deviceHandle) - self._check_for_error(err, "saCloseDevice") + self.check_for_error(err, "saCloseDevice") self.log.info(f"Closed Device with handle num: {self.deviceHandle.value}") super().close() @@ -670,7 +667,7 @@ def abort(self) -> None: "without ever calling initiate()" ) - self._check_for_error(err, "saAbort", extrainfo) + self.check_for_error(err, "saAbort", extrainfo) def preset(self) -> None: """ @@ -680,7 +677,7 @@ def preset(self) -> None: self.log.warning("Performing hardware-reset of device!") err = self.dll.saPreset(self.deviceHandle) - self._check_for_error(err, "saPreset") + self.check_for_error(err, "saPreset") super().close() def _get_device_type(self) -> str: @@ -693,7 +690,7 @@ def _get_device_type(self) -> str: devTypePnt = ct.pointer(devType) err = self.dll.saGetDeviceType(self.deviceHandle, devTypePnt) - self._check_for_error(err, "saGetDeviceType") + self.check_for_error(err, "saGetDeviceType") if devType.value == self.hf.saDeviceTypeNone: dev = "No device" @@ -730,7 +727,7 @@ def QuerySweep(self) -> tuple[int, float, float]: ct.pointer(start_freq), ct.pointer(stepsize), ) - self._check_for_error(err, "saQuerySweepInfo") + self.check_for_error(err, "saQuerySweepInfo") return sweep_len.value, start_freq.value, stepsize.value def _get_sweep_data(self) -> npt.NDArray: @@ -757,7 +754,7 @@ def _get_sweep_data(self) -> npt.NDArray: sleep(self.sleep_time.get()) # Added extra sleep for updating issue err = self.dll.saGetSweep_32f(self.deviceHandle, minarr, maxarr) - self._check_for_error(err, "saGetSweep_32f") + self.check_for_error(err, "saGetSweep_32f") data += datamin return data / Navg @@ -789,12 +786,8 @@ def _get_power_at_freq(self) -> float: sleep(2 * self.sleep_time.get()) return max_power - @staticmethod def check_for_error( - err: int, - source: str, - extrainfo: str | None = None, - logger: logging.Logger | logging.LoggerAdapter[logging.Logger] = log, + self, err: int, source: str, extrainfo: str | None = None ) -> None: if err != saStatus.saNoError: err_str = saStatus(err).name @@ -805,7 +798,7 @@ def check_for_error( ) if extrainfo is not None: msg = msg + f"\n Extra info: {extrainfo}" - logger.warning(msg) + self.log.warning(msg) else: msg = ( f"During call of {source} the following Error: {err_str} was raised" @@ -817,14 +810,7 @@ def check_for_error( msg = f"Call to {source} was successful" if extrainfo is not None: msg = msg + f"\n Extra info: {extrainfo}" - logger.info(msg) - - def _check_for_error( - self, err: int, source: str, extrainfo: str | None = None - ) -> None: - # log to the instrument logger, which does not log while the instrument - # is closed by the garbage collector - self.check_for_error(err, source, extrainfo, logger=self.log) + self.log.info(msg) def get_idn(self) -> dict[str, str | None]: output: dict[str, str | None] = {} @@ -832,14 +818,14 @@ def get_idn(self) -> dict[str, str | None]: output["model"] = self._get_device_type() serialnumber = ct.c_int32() err = self.dll.saGetSerialNumber(self.deviceHandle, ct.pointer(serialnumber)) - self._check_for_error(err, "saGetSerialNumber") + self.check_for_error(err, "saGetSerialNumber") output["serial"] = str(serialnumber.value) fw_version = (ct.c_char * 17)() # the manual says that this must be at least 16 char # but not clear if that includes a termination zero so # make it 17 just in case err = self.dll.saGetFirmwareString(self.deviceHandle, fw_version) - self._check_for_error(err, "saGetFirmwareString") + self.check_for_error(err, "saGetFirmwareString") output["firmware"] = fw_version.value.decode("ascii") return output From 6ed71ce3363574faad0df1f909bfab18f9baad48 Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Sun, 15 Nov 2026 10:51:07 +0100 Subject: [PATCH 18/19] Fix mypy error in InstrumentMeta.__call__ mypy resolves cls.__new__ to the __new__ of the metaclass rather than that of the class, so type the class as Any. --- src/qcodes/instrument/instrument_meta.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/qcodes/instrument/instrument_meta.py b/src/qcodes/instrument/instrument_meta.py index 1cd864bcca8..810258f26ec 100644 --- a/src/qcodes/instrument/instrument_meta.py +++ b/src/qcodes/instrument/instrument_meta.py @@ -35,8 +35,11 @@ def __call__(cls, *args: Any, **kwargs: Any) -> Any: completes successfully, and to close the instance if `__init__` or that code raises. """ - # Create and initialize the instance like type.__call__ does. - new_inst: Any = cls.__new__(cls, *args, **kwargs) + # Create and initialize the instance like type.__call__ does. Looking + # up __new__ on the class finds the __new__ of the class, but type + # checkers would resolve it to the __new__ of this metaclass. + instrument_class: Any = cls + new_inst = instrument_class.__new__(cls, *args, **kwargs) if not issubclass(type(new_inst), cls): return new_inst try: From 03566952063d9fd1d41e0c794f7eaf3af532ae9e Mon Sep 17 00:00:00 2001 From: "Jens H. Nielsen" Date: Mon, 16 Nov 2026 16:45:26 +0100 Subject: [PATCH 19/19] Address review comments on instrument initialization - Do not close instruments that fail before Instrument.__init__ has completed, e.g. because a driver validates its arguments first. Their close methods rely on the name, parameters and logger that it sets up, so closing them only failed and added a misleading note to the error. - Like type.__call__, only initialize objects returned by __new__ that actually inherit from the class, not virtual subclasses registered with the ABCMeta. - Correct the newsfragment: __init__ returning a value already raised a TypeError. - Share the automatic_gc_disabled fixture through tests/conftest.py. --- docs/changes/newsfragments/8769.improved.2 | 7 +- src/qcodes/instrument/instrument.py | 22 +++++-- src/qcodes/instrument/instrument_meta.py | 5 +- tests/conftest.py | 13 ++++ tests/test_instrument.py | 76 ++++++++++++++++++---- tests/test_visa.py | 35 ++++------ 6 files changed, 115 insertions(+), 43 deletions(-) diff --git a/docs/changes/newsfragments/8769.improved.2 b/docs/changes/newsfragments/8769.improved.2 index 823d0349740..ccd80913d7a 100644 --- a/docs/changes/newsfragments/8769.improved.2 +++ b/docs/changes/newsfragments/8769.improved.2 @@ -3,6 +3,9 @@ acquired before the failure, such as an open VISA connection, are freed immediat when the instrument is garbage collected. Previously, retrying to create an instrument for a resource that can only be opened once could fail until the garbage collector had run. This also applies to instruments that cannot be registered, e.g. because their name is already in -use, or that have abstract parameters, and to instruments whose ``__init__`` returns a value, which -now raises a ``TypeError`` like for other classes. +use, or that have abstract parameters, and to instruments whose ``__init__`` returns a value (which +raises a ``TypeError``). If closing the instrument fails too, this is added as a note to the error of the initialization. +Instruments that fail before ``Instrument.__init__`` has completed, e.g. because a driver validates +its arguments first, are not closed, since close methods rely on the name, parameters and logger +that it sets up. diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index 21584f6e774..d3c82e82252 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -35,8 +35,13 @@ def write(self, cmd: str) -> None: ... class _InstrumentState(Enum): """The stages of the lifecycle of an :class:`Instrument`.""" + CREATED = auto() + """ + The instrument has been created, but ``Instrument.__init__`` has not + completed, so it has no name, parameters or logger yet. + """ OPEN = auto() - """The instrument is being initialized or has been initialized.""" + """``Instrument.__init__`` has completed and the instrument is not closed.""" CLOSED = auto() """ The instrument has been closed and its attributes stripped, or its @@ -82,12 +87,13 @@ class Instrument(InstrumentBase, metaclass=instrument_meta_class): _type: type[Instrument] | None = None _instances: ClassVar[weakref.WeakSet[Instrument]] = weakref.WeakSet() # Name mangled so that it cannot clash with attributes of subclasses. - __state: _InstrumentState = _InstrumentState.OPEN + __state: _InstrumentState = _InstrumentState.CREATED def __init__(self, name: str, **kwargs: Unpack[InstrumentBaseKWArgs]) -> None: self._t0 = time.time() super().__init__(name=name, **kwargs) + self.__state = _InstrumentState.OPEN self.IDN = self.add_parameter("IDN", get_cmd=self.get_idn, vals=Anything()) """ @@ -261,9 +267,17 @@ def _close_after_failed_initialization(self, error: BaseException) -> None: sees why the initialization failed. Closing is not retried when the instrument is garbage collected, since it would most likely fail in the same way. + + An instrument whose initialization failed before + ``Instrument.__init__`` completed, e.g. because a driver validates its + arguments before calling it, is not closed: it has no name, parameters + or logger, which close methods rely on, so closing it would only fail + too. """ - if self.__state is _InstrumentState.CLOSED: - # e.g. closed by the subclass itself before raising + if self.__state is not _InstrumentState.OPEN: + # Either closed by the subclass itself before raising, or + # Instrument.__init__ has not completed. + self.__state = _InstrumentState.CLOSED return try: self.close() diff --git a/src/qcodes/instrument/instrument_meta.py b/src/qcodes/instrument/instrument_meta.py index 810258f26ec..eb0617a898d 100644 --- a/src/qcodes/instrument/instrument_meta.py +++ b/src/qcodes/instrument/instrument_meta.py @@ -40,7 +40,10 @@ def __call__(cls, *args: Any, **kwargs: Any) -> Any: # checkers would resolve it to the __new__ of this metaclass. instrument_class: Any = cls new_inst = instrument_class.__new__(cls, *args, **kwargs) - if not issubclass(type(new_inst), cls): + # Like type.__call__, only initialize actual instances of cls, which + # unlike issubclass excludes virtual subclasses registered with the + # ABCMeta. + if cls not in type(new_inst).__mro__: return new_inst try: result = type(new_inst).__init__(new_inst, *args, **kwargs) diff --git a/tests/conftest.py b/tests/conftest.py index 766d94d1fba..f26ce52b125 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -1,6 +1,7 @@ from __future__ import annotations import copy +import gc import os import sys import threading @@ -127,6 +128,18 @@ def reset_state_on_exit() -> Generator[None, None, None]: Station.default = None +@pytest.fixture(scope="function", name="automatic_gc_disabled") +def _automatic_gc_disabled() -> Generator[None, None, None]: + """Disable automatic garbage collection so that only the test triggers it.""" + was_enabled = gc.isenabled() + gc.disable() + try: + yield + finally: + if was_enabled: + gc.enable() + + @pytest.fixture(scope="function", autouse=True) def close_db_connections() -> Generator[None, None, None]: """ diff --git a/tests/test_instrument.py b/tests/test_instrument.py index daf8d63a0d7..6e0ecf039a9 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -12,7 +12,7 @@ import socket import sys import weakref -from typing import TYPE_CHECKING, Any, assert_type +from typing import TYPE_CHECKING, Any, assert_type, cast from weakref import WeakValueDictionary import pytest @@ -40,6 +40,7 @@ from qcodes.utils import strip_attrs if TYPE_CHECKING: + from abc import ABCMeta from collections.abc import Iterator, Sequence from qcodes.metadatable.metadatable_base import Snapshot, SnapshotUpdate @@ -91,18 +92,6 @@ def _close_before_and_after() -> Iterator[None]: Instrument.close_all() -@pytest.fixture(name="automatic_gc_disabled", scope="function") -def _automatic_gc_disabled() -> Iterator[None]: - """Disable automatic garbage collection so that only the test triggers it.""" - was_enabled = gc.isenabled() - gc.disable() - try: - yield - finally: - if was_enabled: - gc.enable() - - def test_instrument_type(request: pytest.FixtureRequest) -> None: # make sure that the type of the instrument is correct. # Due to our use of a metaclass for instrument this could be @@ -856,6 +845,67 @@ def __new__(cls, *args: Any, **kwargs: Any) -> Any: assert OtherInstrument("other") is other +def test_instrument_whose_new_returns_virtual_subclass_returns_it() -> None: + """ + Like for other classes, an object of a virtual subclass, i.e. one that is + registered with the ABCMeta rather than inheriting from the class, that + ``__new__`` returns is returned as is, without initializing it again. + """ + + class Foreign: + def __init__(self, *args: Any) -> None: + self.init_args = args + + foreign = Foreign("original") + + class ForeignInstrument(Instrument): + def __new__(cls, *args: Any, **kwargs: Any) -> Any: + return foreign + + # Instrument's metaclass is an ABCMeta, which type checkers do not see + cast("ABCMeta", ForeignInstrument).register(Foreign) + + assert ForeignInstrument("foreign") is foreign + assert foreign.init_args == ("original",) + assert not Instrument.exist("foreign") + + +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +def test_instrument_that_fails_before_instrument_init_is_not_closed() -> None: + """ + An instrument that fails before ``Instrument.__init__`` has completed, + e.g. because it validates its arguments first, is not closed, neither right + away nor when garbage collected, since it has no name, parameters or + logger that close methods rely on. Closing it could therefore only fail + and add a misleading note to the error. + """ + closed: list[str] = [] + created: list[weakref.ref[Instrument]] = [] + + class ValidatesFirst(Instrument): + def __init__(self, name: str, address: str) -> None: + created.append(weakref.ref(self)) + if "::" not in address: + raise ValueError(f"Malformed address {address!r}") + super().__init__(name) + + def close(self) -> None: + closed.append(self.name) + super().close() + + with pytest.raises(ValueError, match="Malformed address") as exc_info: + ValidatesFirst("validates_first", "not-an-address") + + assert getattr(exc_info.value, "__notes__", None) is None + # the traceback of the error refers to the instrument + del exc_info + gc.collect() + + (instrument,) = created + assert instrument() is None + assert closed == [] + + @pytest.mark.usefixtures("close_before_and_after") def test_instrument_with_name_in_use_is_closed_right_away() -> None: """ diff --git a/tests/test_visa.py b/tests/test_visa.py index 32e48dccb7c..b2296aade74 100644 --- a/tests/test_visa.py +++ b/tests/test_visa.py @@ -141,6 +141,7 @@ def _make_mock_visa() -> "Generator[MockVisa, None, None]": mv.close() +@pytest.mark.usefixtures("automatic_gc_disabled") def test_visa_gc_closes_connection() -> None: def use_magnet() -> pyvisa.ResourceManager: x = AMIModel430( @@ -157,15 +158,8 @@ def use_magnet() -> pyvisa.ResourceManager: # ensure that any unused instruments that have not been gced are gced before running gc.collect() - gc_was_enabled = gc.isenabled() - # so that only the explicit collection below collects the instrument - gc.disable() - try: - rm = use_magnet() - gc.collect() - finally: - if gc_was_enabled: - gc.enable() + rm = use_magnet() + gc.collect() # at this stage the instrument created in use_magnet has gone out of scope # and we have triggered an explicit gc, so the VISA handle should be closed # and the instrument should no longer be in the instrument registry @@ -173,6 +167,7 @@ def use_magnet() -> pyvisa.ResourceManager: assert len(rm.list_opened_resources()) == 0 +@pytest.mark.usefixtures("automatic_gc_disabled") def test_visa_handle_is_closed_right_away_if_initialization_fails() -> None: """ If the initialization of a VISA instrument fails after it has connected, @@ -187,20 +182,14 @@ def __init__(self, name: str, address: str, **kwargs: Any) -> None: handles.append(self.visa_handle) raise RuntimeError("Unexpected reply") - gc_was_enabled = gc.isenabled() - gc.disable() - try: - with pytest.raises(RuntimeError, match="Unexpected reply"): - FailsAfterConnecting( - "x", address="GPIB::1::INSTR", pyvisa_sim_file="AMI430.yaml" - ) - (handle,) = handles - resource_manager = handle.visalib.resource_manager - assert resource_manager is not None - assert resource_manager.list_opened_resources() == [] - finally: - if gc_was_enabled: - gc.enable() + with pytest.raises(RuntimeError, match="Unexpected reply"): + FailsAfterConnecting( + "x", address="GPIB::1::INSTR", pyvisa_sim_file="AMI430.yaml" + ) + (handle,) = handles + resource_manager = handle.visalib.resource_manager + assert resource_manager is not None + assert resource_manager.list_opened_resources() == [] def test_ask_write_local(mock_visa: MockVisa) -> None: