Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
50815a2
Do not close instruments again when they are garbage collected
jenshnielsen Nov 14, 2026
e32d8a6
Fully close Galil and MiniCircuits USB HID instruments
jenshnielsen Nov 14, 2026
70cd16a
Warn when the garbage collector closes an unclosed instrument
jenshnielsen Nov 14, 2026
5a49b83
Close instruments right away when their initialization fails
jenshnielsen Nov 14, 2026
a6d0b69
Do not log when closing VISA handles from the finalizer
jenshnielsen Nov 14, 2026
6f39f9d
Fix stale comment about the logger of IPToVisa
jenshnielsen Nov 14, 2026
37b0601
Do not log from instruments while the garbage collector closes them
jenshnielsen Nov 14, 2026
97f2ec4
Make closing instruments that are closed or partly initialized safe
jenshnielsen Nov 14, 2026
528a3ad
Document how to write close methods of instrument drivers
jenshnielsen Nov 14, 2026
ba10cea
Address review of closing instruments
jenshnielsen Nov 14, 2026
86a59c5
Keep the instrument finalizer working late in interpreter shutdown
jenshnielsen Nov 14, 2026
b7b6d0d
Rename newsfragments for PR 8769
jenshnielsen Nov 15, 2026
cf7a7ee
Assign the session of the Keysight drivers in __init__
jenshnielsen Nov 15, 2026
5e8c173
Close Keysight sessions opened with a warning status
jenshnielsen Nov 15, 2026
3605038
Test the drivers changed for closing with fake vendor libraries
jenshnielsen Nov 15, 2026
5d93da2
Remove the ResourceWarning about unclosed instruments
jenshnielsen Nov 15, 2026
1140829
Make SignalHoundUSBSA124B.check_for_error log through the instrument …
jenshnielsen Nov 15, 2026
6ed71ce
Fix mypy error in InstrumentMeta.__call__
jenshnielsen Nov 15, 2026
0356695
Address review comments on instrument initialization
jenshnielsen Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/changes/newsfragments/8769.improved.1
Original file line number Diff line number Diff line change
@@ -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``.
11 changes: 11 additions & 0 deletions docs/changes/newsfragments/8769.improved.2
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions docs/changes/newsfragments/8769.improved.3
Original file line number Diff line number Diff line change
@@ -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.
4 changes: 4 additions & 0 deletions docs/changes/newsfragments/8769.improved.4
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions docs/changes/newsfragments/8769.improved_driver.1
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions docs/changes/newsfragments/8769.improved_driver.2
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions docs/changes/newsfragments/8769.improved_driver.3
Original file line number Diff line number Diff line change
@@ -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.
3 changes: 3 additions & 0 deletions docs/changes/newsfragments/8769.underthehood
Original file line number Diff line number Diff line change
@@ -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.
75 changes: 73 additions & 2 deletions docs/examples/writing_drivers/Creating-Instrument-Drivers.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -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)."
]
},
{
Expand Down Expand Up @@ -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`."
]
},
{
Expand Down Expand Up @@ -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",
Expand Down
Loading
Loading