diff --git a/docs/changes/newsfragments/8769.improved.1 b/docs/changes/newsfragments/8769.improved.1 new file mode 100644 index 000000000000..d482c3db328f --- /dev/null +++ b/docs/changes/newsfragments/8769.improved.1 @@ -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/docs/changes/newsfragments/8769.improved.2 b/docs/changes/newsfragments/8769.improved.2 new file mode 100644 index 000000000000..ccd80913d7a2 --- /dev/null +++ b/docs/changes/newsfragments/8769.improved.2 @@ -0,0 +1,11 @@ +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 +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/docs/changes/newsfragments/8769.improved.3 b/docs/changes/newsfragments/8769.improved.3 new file mode 100644 index 000000000000..fbd7b55f02d3 --- /dev/null +++ b/docs/changes/newsfragments/8769.improved.3 @@ -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/8769.improved.4 b/docs/changes/newsfragments/8769.improved.4 new file mode 100644 index 000000000000..0aeb227f1aaf --- /dev/null +++ b/docs/changes/newsfragments/8769.improved.4 @@ -0,0 +1,4 @@ +``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_driver.1 b/docs/changes/newsfragments/8769.improved_driver.1 new file mode 100644 index 000000000000..8db49be29190 --- /dev/null +++ b/docs/changes/newsfragments/8769.improved_driver.1 @@ -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/docs/changes/newsfragments/8769.improved_driver.2 b/docs/changes/newsfragments/8769.improved_driver.2 new file mode 100644 index 000000000000..4fc8926cc33c --- /dev/null +++ b/docs/changes/newsfragments/8769.improved_driver.2 @@ -0,0 +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`` is therefore no longer a +static method, so it can no longer be called on the class without an instance. diff --git a/docs/changes/newsfragments/8769.improved_driver.3 b/docs/changes/newsfragments/8769.improved_driver.3 new file mode 100644 index 000000000000..b99ebfb17b58 --- /dev/null +++ b/docs/changes/newsfragments/8769.improved_driver.3 @@ -0,0 +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. ``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/changes/newsfragments/8769.underthehood b/docs/changes/newsfragments/8769.underthehood new file mode 100644 index 000000000000..91085a1e2a08 --- /dev/null +++ b/docs/changes/newsfragments/8769.underthehood @@ -0,0 +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. diff --git a/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb b/docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb index c6f5faa07345..fb42cea6de67 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, 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. 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." + ] + }, + { + "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", diff --git a/src/qcodes/instrument/instrument.py b/src/qcodes/instrument/instrument.py index fc3acfa90432..d3c82e822521 100644 --- a/src/qcodes/instrument/instrument.py +++ b/src/qcodes/instrument/instrument.py @@ -5,6 +5,7 @@ import logging import time import weakref +from enum import Enum, auto from typing import TYPE_CHECKING, Any, ClassVar, Protocol, overload from qcodes.utils import strip_attrs @@ -31,6 +32,29 @@ def ask(self, cmd: str) -> str: ... 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() + """``Instrument.__init__`` has completed and the instrument is not closed.""" + CLOSED = auto() + """ + 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 # both the args and return type hints. # Since our metaclass does not modify the signature @@ -62,11 +86,14 @@ 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.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()) """ @@ -148,8 +175,35 @@ def __repr__(self) -> str: """Simplified repr giving just the class and name.""" return f"<{type(self).__name__}: {self.name}>" - def __del__(self) -> None: - """Close the instrument and remove its instance record.""" + 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, + _finalizing: _InstrumentState = _InstrumentState.FINALIZING, + ) -> None: + """ + 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 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 _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 + # 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 @@ -159,13 +213,24 @@ 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. + 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() @@ -184,7 +249,50 @@ def close(self) -> None: for channel in channellist: strip_attrs(channel, whitelist=["_short_name", "_parent"]) - strip_attrs(self, whitelist=["_short_name"]) + # 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, 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 + 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 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() + 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. 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}" + ) + finally: + self.__state = _InstrumentState.CLOSED @classmethod def close_all( @@ -290,14 +398,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/instrument_base.py b/src/qcodes/instrument/instrument_base.py index 1947e494f018..b5176c4c6c81 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/instrument_meta.py b/src/qcodes/instrument/instrument_meta.py index 0e907a28b0d8..eb0617a898db 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__ 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__` (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,17 +31,36 @@ 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 add code that runs only if `__init__` + completes successfully, and to close the instance if `__init__` or that + code raises. """ - new_inst = super().__call__(*args, **kwargs) - 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) + # 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) + # 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) + 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 286b0a6ca266..3fef78f000d5 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,16 @@ def _connect(self) -> None: def _disconnect(self) -> None: if self._socket is None: return - log.info("Socket shutdown") - self._socket.shutdown(socket.SHUT_RDWR) - log.info("Socket closing") + self.log.info("Socket shutdown") + 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() - log.info("Socket closed") + self.log.info("Socket closed") self._socket = None def set_timeout(self, timeout: float) -> None: @@ -167,21 +169,24 @@ 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: """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/ip_to_visa.py b/src/qcodes/instrument/ip_to_visa.py index 5f66698dd24e..6c0e73a63f47 100644 --- a/src/qcodes/instrument/ip_to_visa.py +++ b/src/qcodes/instrument/ip_to_visa.py @@ -5,14 +5,12 @@ 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 -# 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 @@ -108,9 +106,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/src/qcodes/instrument/visa.py b/src/qcodes/instrument/visa.py index fb4b05c3e07e..fba27749f253 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 @@ -271,8 +264,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/src/qcodes/instrument_drivers/Galil/dmc_41x3.py b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py index 758a06424bec..342efab8aa52 100644 --- a/src/qcodes/instrument_drivers/Galil/dmc_41x3.py +++ b/src/qcodes/instrument_drivers/Galil/dmc_41x3.py @@ -176,9 +176,14 @@ def timeout(self, val: int) -> None: def close(self) -> None: """ - Close connection to the instrument - """ - self.g.GClose() + Close connection to the instrument and irreversibly tear down the + instrument. + """ + # 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 250345c73470..985d666be81c 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) @@ -159,16 +158,25 @@ 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(self._session) + 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 def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" @@ -295,5 +303,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 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 3720be3b6051..9334351510a2 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") @@ -294,16 +293,25 @@ 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(self._session) + 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 def get_idn(self) -> dict[str, str | None]: """Generates the ``*IDN`` dictionary for qcodes""" @@ -405,5 +413,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 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/Minicircuits/USBHIDMixin.py b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py index b5de6d55eecb..5293dcdb99d8 100644 --- a/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py +++ b/src/qcodes/instrument_drivers/Minicircuits/USBHIDMixin.py @@ -165,7 +165,12 @@ def ask_raw(self, cmd: str) -> str: return self._unpack_string(response) def close(self) -> None: - self._device.close() + """Disconnect and irreversibly tear down the instrument.""" + # 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 def enumerate_devices(cls) -> list[str]: diff --git a/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py b/src/qcodes/instrument_drivers/QuantumDesign/DynaCoolPPMS/DynaCool.py index 1860c14f5320..aa3e23f61ead 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 @@ -458,15 +459,26 @@ 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}" + ) + 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 8ee870b1e959..95fc8a22fbf4 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): """ @@ -207,7 +204,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,7 +534,7 @@ 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") @@ -560,19 +557,19 @@ def sync_parameters(self) -> None: 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") # 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") 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()), @@ -624,38 +621,43 @@ def openDevice(self) -> None: """ Opens connection to the instrument """ - log.info("Opening Device") - self.deviceHandle = ct.c_int(0) - deviceHandlePnt = ct.pointer(self.deviceHandle) - err = self.dll.saOpenDevice(deviceHandlePnt) + 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") + # 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: """ Close connection to the instrument. """ - log.info(f"Closing Device with handle num: {self.deviceHandle.value}") - - try: - self.abort() - 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") - - err = self.dll.saCloseDevice(self.deviceHandle) - self.check_for_error(err, "saCloseDevice") - 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: """ Abort any running acquisition. """ - log.info("Stopping acquisition") + self.log.info("Stopping acquisition") err = self.dll.saAbort(self.deviceHandle) extrainfo: str | None = None @@ -672,7 +674,7 @@ 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") @@ -682,7 +684,7 @@ 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) @@ -784,8 +786,9 @@ 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) -> None: + def check_for_error( + self, err: int, source: str, extrainfo: str | None = None + ) -> None: if err != saStatus.saNoError: err_str = saStatus(err).name if err > 0: @@ -795,7 +798,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) + self.log.warning(msg) else: msg = ( f"During call of {source} the following Error: {err_str} was raised" @@ -807,7 +810,7 @@ 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) + self.log.info(msg) def get_idn(self) -> dict[str, str | None]: output: dict[str, str | None] = {} diff --git a/src/qcodes/logger/instrument_logger.py b/src/qcodes/logger/instrument_logger.py index 665a8417919f..8c337b5370bc 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/conftest.py b/tests/conftest.py index 766d94d1fba7..f26ce52b125e 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/drivers/test_close_drivers.py b/tests/drivers/test_close_drivers.py new file mode 100644 index 000000000000..fc6b1947d8ea --- /dev/null +++ b/tests/drivers/test_close_drivers.py @@ -0,0 +1,165 @@ +""" +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, or initialized +with fake vendor libraries. The SignalHound driver is tested with a fake of its +library in test_signal_hound_usb_sa124b.py. +""" + +import ctypes +from typing import Any +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 +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() + + +@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 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=error): + instrument.close() + + visa_handle.close.assert_called_once() + + +_KEYSIGHT_DRIVERS = 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"), + ], +) + + +@_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() + # 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), + 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") + + +@_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") + + +class _SucceedingIviDll: + """A fake IVI DLL whose functions all succeed without returning any data.""" + + def __init__(self) -> None: + self._functions: dict[str, mock.MagicMock] = {} + + 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_galil_dmc_41x3.py b/tests/drivers/test_galil_dmc_41x3.py new file mode 100644 index 000000000000..7741527a2477 --- /dev/null +++ b/tests/drivers/test_galil_dmc_41x3.py @@ -0,0 +1,73 @@ +"""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 + +import qcodes.instrument_drivers +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) + # 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( + 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") + # 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 new file mode 100644 index 000000000000..d186293c76a6 --- /dev/null +++ b/tests/drivers/test_minicircuits_usb_hid_mixin.py @@ -0,0 +1,99 @@ +"""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 + +import qcodes.instrument_drivers +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) + # 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() + 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) + if hasattr(qcodes.instrument_drivers, "Minicircuits"): + delattr(qcodes.instrument_drivers, "Minicircuits") + + +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") + # 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/drivers/test_signal_hound_usb_sa124b.py b/tests/drivers/test_signal_hound_usb_sa124b.py index 34ee5c44996f..a6708a0de39d 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 be6d9ec192ae..6e0ecf039a92 100644 --- a/tests/test_instrument.py +++ b/tests/test_instrument.py @@ -9,8 +9,10 @@ import io import logging import re +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 @@ -19,9 +21,12 @@ from qcodes.instrument import ( Instrument, InstrumentBase, + InstrumentChannel, InstrumentModule, + IPInstrument, find_or_create_instrument, ) +from qcodes.instrument import instrument as instrument_module from qcodes.instrument_drivers.mock_instruments import ( DummyBase, DummyChannelInstrument, @@ -32,8 +37,10 @@ ) from qcodes.metadatable import Metadatable from qcodes.parameters import Function, Parameter +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 @@ -85,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 @@ -701,6 +696,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 @@ -715,6 +711,420 @@ def use_some_instrument() -> None: assert len(Instrument._all_instruments) == 0 +def _instrument_class_recording_close( + 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``. 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") + + def close(self) -> None: + closed.append(self.name) + super().close() + + return InstrumentRecordingClose + + +@pytest.mark.usefixtures("close_before_and_after", "automatic_gc_disabled") +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", "automatic_gc_disabled") +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 + not closed again when garbage collected. + """ + closed: list[str] = [] + 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") + + assert closed == ["failing"] + + gc.collect() + + (instrument,) = created + assert instrument() is None + assert closed == ["failing"] + + +@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] = [] + 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: + 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')" + ) + ] + # 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 + + +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: + """ + 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") + + 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 + 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_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", "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") + + 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: + """ + 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(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: + """ + 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() + + +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", "automatic_gc_disabled") +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): + 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") diff --git a/tests/test_visa.py b/tests/test_visa.py index 0466891ce6b2..b2296aade74f 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,8 @@ def _make_mock_visa() -> "Generator[MockVisa, None, None]": mv.close() -def test_visa_gc_closes_connection(caplog: pytest.LogCaptureFixture) -> None: +@pytest.mark.usefixtures("automatic_gc_disabled") +def test_visa_gc_closes_connection() -> None: def use_magnet() -> pyvisa.ResourceManager: x = AMIModel430( "x", @@ -158,23 +158,38 @@ 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() - gc.collect() + 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 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 - ) + + +@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, + 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") + + 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: