[Python][builder mode] Replace __del__ methods with weakref.finalize (#3350)

This issue primarily affects Docker environments where Python module teardown order is less predictable than in wheel installations. The weakref.finalize() approach is recommended by Python documentation as more reliable than __del__ methods during interpreter shutdown.

---------

Signed-off-by: Pradnya Khalate <[email protected]>

Author: khalatepradnya

python/cudaq/kernel/captured_data.py

@@ -7,8 +7,9 @@
 # ============================================================================ #
 
 import uuid
-import numpy as np
+import weakref
 
+import numpy as np
 from cudaq.mlir._mlir_libs._quakeDialects import cudaq_runtime
 from cudaq.mlir.dialects import arith, cc, func
 from cudaq.mlir.ir import (ComplexType, F32Type, F64Type, FlatSymbolRefAttr,
@@ -34,20 +35,29 @@ def __init__(self, **kwargs):
         self.loc = kwargs['loc'] if 'loc' in kwargs else None
         self.name = kwargs['name'] if 'name' in kwargs else None
         self.module = kwargs['module'] if 'module' in kwargs else None
+        self._finalizer = weakref.finalize(self, CapturedDataStorage._cleanup,
+                                           self.cudaqStateIDs, self.arrayIDs)
+
+    @staticmethod
+    def _cleanup(state_ids, array_ids):
+        """
+        Safely clean up resources associated with captured data during garbage collection.
+        This method is to be used with `weakref.finalize()` as an alternative to `__del__`,
+        such that it handles Python interpreter shutdown gracefully, catching exceptions
+        that occur when modules are unloaded before they are cleaned up.
+        """
+        try:
+            cudaq_runtime.deletePointersToCudaqState(state_ids)
+            cudaq_runtime.deletePointersToStateData(array_ids)
+        except (ImportError, AttributeError):
+            pass
 
     def setKernelContext(self, ctx, loc, name, module):
         self.ctx = ctx
         self.loc = loc
         self.name = name
         self.module = module
 
-    def __del__(self):
-        """
-        Remove pointers to stored data for the current kernel.
-        """
-        cudaq_runtime.deletePointersToCudaqState(self.cudaqStateIDs)
-        cudaq_runtime.deletePointersToStateData(self.arrayIDs)
-
     def getIntegerAttr(self, type, value):
         """
         Return an MLIR Integer Attribute of the given IntegerType.

python/cudaq/kernel/kernel_builder.py

@@ -6,13 +6,14 @@
 # the terms of the Apache License 2.0 which accompanies this distribution.     #
 # ============================================================================ #
 
-import numpy as np
 import random
 import re
 import string
+import weakref
 from functools import partialmethod
 from typing import get_origin
 
+import numpy as np
 from cudaq.mlir.ir import (
     BoolAttr,
     Block,
@@ -316,12 +317,20 @@ def __init__(self, argTypeList):
 
             self.insertPoint = InsertionPoint.at_block_begin(e)
 
-    def __del__(self):
+        self._finalizer = weakref.finalize(self, PyKernel._cleanup,
+                                           self.capturedDataStorage)
+
+    @staticmethod
+    def _cleanup(capturedDataStorage):
         """
-        When a kernel builder is deleted we need to clean up 
-        any state data if there is any.
+        Cleanup function to be called when the `PyKernel` instance is garbage 
+        collected. This resource management method is used with `weakref.finalize()`
+        to ensure proper cleanup of resources. Note that this method is intentionally
+        empty since `CapturedDataStorage` has its own `finalizer`. However, it is still
+        included for maintaining the reference to `CapturedDataStorage` until the
+        `PyKernel` instance is garbage collected ensuring proper cleanup order.
         """
-        self.capturedDataStorage.__del__()
+        pass
 
     def __processArgType(self, ty):
         """