✨ Refactor QDMI Devices and Fix Singleton Handling

CHANGELOG.md

@@ -21,6 +21,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- 🎨 Extract the singleton handling of QDMI devices and make it thread-safe ([#1347]) ([**@ystade**])
 - 👷 Stop testing on `ubuntu-22.04` and `ubuntu-22.04-arm` runners ([#1359]) ([**@denialhaag**], [**@burgholzer**])
 - 👷 Stop testing with `clang-19` and start testing with `clang-21` ([#1359]) ([**@denialhaag**], [**@burgholzer**])
 - 👷 Fix macOS tests with Homebrew Clang via new `munich-quantum-toolkit/workflows` version ([#1359]) ([**@denialhaag**], [**@burgholzer**])
@@ -271,6 +272,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 <!-- PR links -->
 
 [#1359]: https://github.com/munich-quantum-toolkit/core/pull/1359
+[#1347]: https://github.com/munich-quantum-toolkit/core/pull/1347
 [#1338]: https://github.com/munich-quantum-toolkit/core/pull/1338
 [#1336]: https://github.com/munich-quantum-toolkit/core/pull/1336
 [#1328]: https://github.com/munich-quantum-toolkit/core/pull/1328

bindings/na/fomac/fomac.cpp

@@ -12,7 +12,7 @@
 // clang-format off
 #include "fomac/FoMaC.hpp"
 #include "na/fomac/Device.hpp"
-#include "na/device/Generator.hpp"
+#include "qdmi/devices/na/Generator.hpp"
 
 #include <pybind11/cast.h>
 #include <pybind11/operators.h>

include/mqt-core/na/fomac/Device.hpp

@@ -11,7 +11,7 @@
 #pragma once
 
 #include "fomac/FoMaC.hpp"
-#include "na/device/Generator.hpp"
+#include "qdmi/devices/na/Generator.hpp"
 
 // NOLINTNEXTLINE(misc-include-cleaner)
 #include <nlohmann/json.hpp>

include/mqt-core/qdmi/devices/base/Device.hpp

@@ -0,0 +1,97 @@
+/*
+ * Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+ * Copyright (c) 2025 Munich Quantum Software Company GmbH
+ * All rights reserved.
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ * Licensed under the MIT License
+ */
+
+#pragma once
+
+/** @file
+ * @brief The generic MQT QDMI device implementation that specific devices
+ * inherit from.
+ */
+
+#include <cassert>
+#include <memory>
+#include <mutex>
+
+// Define a macro for hidden visibility, which works on GCC and Clang.
+#if defined(__GNUC__) || defined(__clang__)
+#define MQT_HIDDEN __attribute__((visibility("hidden")))
+#else
+#define MQT_HIDDEN
+#endif
+
+namespace qdmi {
+template <class ConcreteType> class SingletonDevice {
+  // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
+  MQT_HIDDEN inline static std::shared_ptr<ConcreteType>* instance = nullptr;
+  // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
+  MQT_HIDDEN inline static std::mutex* mutex = new std::mutex;
+
+protected:
+  /// @brief Protected constructor to enforce the singleton pattern.
+  SingletonDevice() = default;
+  // Allow std::make_shared to access the protected constructor.
+  friend class std::shared_ptr<ConcreteType>;
+
+public:
+  // Delete move constructor and move assignment operator.
+  SingletonDevice(SingletonDevice&&) = delete;
+  SingletonDevice& operator=(SingletonDevice&&) = delete;
+  // Delete copy constructor and assignment operator to enforce singleton.
+  SingletonDevice(const SingletonDevice&) = delete;
+  SingletonDevice& operator=(const SingletonDevice&) = delete;
+
+  /// @brief Destructor for the SingletonDevice class.
+  virtual ~SingletonDevice() = default;
+
+  /**
+   * @brief Initializes the singleton instance.
+   * @details Must be called before `get()`.
+   */
+  static void initialize() {
+    const std::scoped_lock lock(*mutex);
+    if (instance == nullptr) {
+      // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
+      instance = new std::shared_ptr<ConcreteType>(new ConcreteType);
+    }
+  }
+
+  /**
+   * @brief Destroys the singleton instance.
+   * @details After this call, `get()` must not be called until a new
+   * `initialize()` call. Any existing shared_ptr will keep the object alive
+   * until they go out of scope.
+   */
+  static void finalize() {
+    const std::scoped_lock lock(*mutex);
+    if (instance != nullptr) {
+      // Reset the shared_ptr to release the managed object.
+      *instance = nullptr;
+      // Delete the shared_ptr object itself.
+      // NOLINTNEXTLINE(cppcoreguidelines-owning-memory)
+      delete instance;
+      instance = nullptr;
+    }
+    // Do NOT delete the static mutex. The mutex is intentionally leaked to
+    // avoid static deinitialization issues (cf. static deinitialization order
+    // fiasco)
+  }
+
+  /**
+   * @brief Get the singleton instance of the device.
+   * @return A shared pointer to the device instance.
+   */
+  [[nodiscard]] static auto get() -> std::shared_ptr<ConcreteType> {
+    const std::scoped_lock lock(*mutex);
+    assert(*instance != nullptr &&
+           "Device not initialized. Call `initialize()` first.");
+    return *instance;
+  }
+};
+} // namespace qdmi

include/mqt-core/qdmi/dd/Device.hpp → include/mqt-core/qdmi/devices/dd/Device.hpp

@@ -17,6 +17,7 @@
 #include "dd/DDDefinitions.hpp"
 #include "dd/Package.hpp"
 #include "mqt_ddsim_qdmi/device.h"
+#include "qdmi/devices/base/Device.hpp"
 
 #include <atomic>
 #include <cstddef>
@@ -31,7 +32,8 @@
 #include <unordered_map>
 
 namespace qdmi::dd {
-class Device final {
+class Device final : public SingletonDevice<Device> {
+  friend class SingletonDevice;
   /// Provides access to the device name.
   std::string name_;
 
@@ -63,9 +65,6 @@ class Device final {
   /// @brief Private constructor to enforce the singleton pattern.
   Device();
 
-  /// @brief The singleton instance.
-  static std::atomic<Device*> instance;
-
 public:
   // Default move constructor and move assignment operator.
   Device(Device&&) = delete;
@@ -75,23 +74,7 @@ class Device final {
   Device& operator=(const Device&) = delete;
 
   /// @brief Destructor for the Device class.
-  ~Device() = default;
-
-  /**
-   * @brief Initializes the singleton instance.
-   * @details Must be called before `get()`.
-   */
-  static void initialize();
-
-  /**
-   * @brief Destroys the singleton instance.
-   * @details After this call, `get()` must not be called until a new
-   * `initialize()` call.
-   */
-  static void finalize();
-
-  /// @returns the singleton instance of the Device class.
-  [[nodiscard]] static auto get() -> Device&;
+  ~Device() override = default;
 
   /**
    * @brief Allocates a new device session.
@@ -264,7 +247,7 @@ struct MQT_DDSIM_QDMI_Device_Job_impl_d {
   /// Constructor for the MQT_DDSIM_QDMI_Device_Job_impl_d.
   explicit MQT_DDSIM_QDMI_Device_Job_impl_d(
       MQT_DDSIM_QDMI_Device_Session_impl_d* session)
-      : session_(session), id_(qdmi::dd::Device::get().generateUniqueID()) {}
+      : session_(session), id_(qdmi::dd::Device::get()->generateUniqueID()) {}
   /**
    * @brief Frees the device job.
    * @note This function just forwards to the session's @ref freeDeviceJob

include/mqt-core/na/device/Device.hpp → include/mqt-core/qdmi/devices/na/Device.hpp

@@ -15,8 +15,8 @@
  */
 
 #include "mqt_na_qdmi/device.h"
+#include "qdmi/devices/base/Device.hpp"
 
-#include <atomic>
 #include <cstddef>
 #include <cstdint>
 #include <memory>
@@ -28,7 +28,8 @@
 #include <vector>
 
 namespace qdmi::na {
-class Device final {
+class Device final : public SingletonDevice<Device> {
+  friend class SingletonDevice;
   /// @brief Provides access to the device name.
   std::string name_;
 
@@ -69,35 +70,16 @@ class Device final {
   /// @brief Private constructor to enforce the singleton pattern.
   Device();
 
-  /// @brief The singleton instance.
-  static std::atomic<Device*> instance;
-
 public:
   // Default move constructor and move assignment operator.
-  Device(Device&&) = default;
-  Device& operator=(Device&&) = default;
+  Device(Device&&) = delete;
+  Device& operator=(Device&&) = delete;
   // Delete copy constructor and assignment operator to enforce singleton.
   Device(const Device&) = delete;
   Device& operator=(const Device&) = delete;
 
   /// @brief Destructor for the Device class.
-  ~Device() = default;
-
-  /**
-   * @brief Initializes the singleton instance.
-   * @details Must be called before `get()`.
-   */
-  static void initialize();
-
-  /**
-   * @brief Destroys the singleton instance.
-   * @details After this call, `get()` must not be called until a new
-   * `initialize()` call.
-   */
-  static void finalize();
-
-  /// @returns the singleton instance of the Device class.
-  [[nodiscard]] static auto get() -> Device&;
+  ~Device() override = default;
 
   /**
    * @brief Allocates a new device session.

include/mqt-core/qdmi/sc/Device.hpp → include/mqt-core/qdmi/devices/sc/Device.hpp

@@ -15,20 +15,20 @@
  */
 
 #include "mqt_sc_qdmi/device.h"
+#include "qdmi/devices/base/Device.hpp"
 
-#include <atomic>
 #include <cstddef>
 #include <cstdint>
 #include <memory>
-#include <optional>
 #include <string>
 #include <unordered_map>
 #include <utility>
 #include <variant>
 #include <vector>
 
 namespace qdmi::sc {
-class Device final {
+class Device final : public SingletonDevice<Device> {
+  friend class SingletonDevice;
   /// @brief Provides access to the device name.
   std::string name_;
 
@@ -52,9 +52,6 @@ class Device final {
   /// @brief Private constructor to enforce the singleton pattern.
   Device();
 
-  /// @brief The singleton instance.
-  static std::atomic<Device*> instance;
-
 public:
   // Delete move constructor and move assignment operator.
   Device(Device&&) = delete;
@@ -64,23 +61,7 @@ class Device final {
   Device& operator=(const Device&) = delete;
 
   /// @brief Destructor for the Device class.
-  ~Device();
-
-  /**
-   * @brief Initializes the singleton instance.
-   * @details Must be called before `get()`.
-   */
-  static void initialize();
-
-  /**
-   * @brief Destroys the singleton instance.
-   * @details After this call, `get()` must not be called until a new
-   * `initialize()` call.
-   */
-  static void finalize();
-
-  /// @returns the singleton instance of the Device class.
-  [[nodiscard]] static auto get() -> Device&;
+  ~Device() override;
 
   /**
    * @brief Allocates a new device session.

src/na/CMakeLists.txt

@@ -7,7 +7,6 @@
 # Licensed under the MIT License
 
 # add subdirectories
-add_subdirectory(device)
 add_subdirectory(fomac)
 
 if(NOT TARGET ${MQT_CORE_TARGET_NAME}-na)

src/na/fomac/Device.cpp

@@ -12,7 +12,7 @@
 
 #include "fomac/FoMaC.hpp"
 #include "ir/Definitions.hpp"
-#include "na/device/Generator.hpp"
+#include "qdmi/devices/na/Generator.hpp"
 
 #include <algorithm>
 #include <array>

src/qdmi/CMakeLists.txt

@@ -6,31 +6,10 @@
 #
 # Licensed under the MIT License
 
-add_subdirectory(dd)
-add_subdirectory(sc)
+add_subdirectory(devices)
+add_subdirectory(driver)
 
-set(TARGET_NAME ${MQT_CORE_TARGET_NAME}-qdmi-driver)
-
-if(NOT TARGET ${TARGET_NAME})
-  # Add driver library
-  add_mqt_core_library(${TARGET_NAME} ALIAS_NAME QDMIDriver)
-
-  # Add sources to target
-  target_sources(${TARGET_NAME} PRIVATE Driver.cpp)
-
-  # Add headers using file sets
-  target_sources(${TARGET_NAME} PUBLIC FILE_SET HEADERS BASE_DIRS ${MQT_CORE_INCLUDE_BUILD_DIR}
-                                       FILES ${MQT_CORE_INCLUDE_BUILD_DIR}/qdmi/Driver.hpp)
-
-  # Add link libraries
-  target_link_libraries(
-    ${TARGET_NAME}
-    PUBLIC qdmi::qdmi
-    PRIVATE MQT::CoreQDMINaDevice MQT::CoreQDMIScDevice MQT::CoreQDMI_DDSIM_Device
-            qdmi::project_warnings)
-
-  # add to list of MQT core targets
-  set(MQT_CORE_TARGETS
-      ${MQT_CORE_TARGETS} ${TARGET_NAME}
-      PARENT_SCOPE)
-endif()
+# add to list of MQT core targets
+set(MQT_CORE_TARGETS
+    ${MQT_CORE_TARGETS}
+    PARENT_SCOPE)

src/qdmi/devices/CMakeLists.txt

@@ -0,0 +1,17 @@
+# Copyright (c) 2023 - 2025 Chair for Design Automation, TUM
+# Copyright (c) 2025 Munich Quantum Software Company GmbH
+# All rights reserved.
+#
+# SPDX-License-Identifier: MIT
+#
+# Licensed under the MIT License
+
+add_subdirectory(base)
+add_subdirectory(na)
+add_subdirectory(dd)
+add_subdirectory(sc)
+
+# add to list of MQT core targets
+set(MQT_CORE_TARGETS
+    ${MQT_CORE_TARGETS}
+    PARENT_SCOPE)