Add destroy() method with handle invalidation, remove GRAPH_NODE_SENTINEL

Replace discard() with destroy() which calls cuGraphDestroyNode and then
zeroes the CUgraphNode resource in the handle box via
invalidate_graph_node_handle. This prevents stale memory access on
destroyed nodes. Properties (type, pred, succ, handle) degrade gracefully
to None/empty for destroyed nodes.

Remove the GRAPH_NODE_SENTINEL (0x1) approach in favor of using NULL for
both sentinels and destroyed nodes, which is simpler and avoids the risk
of passing 0x1 to driver APIs that treat it as a valid pointer.

Made-with: Cursor

Author: Andy-Jost

cuda_core/cuda/core/_cpp/resource_handles.cpp

@@ -957,7 +957,7 @@ GraphHandle create_graph_handle_ref(CUgraph graph, const GraphHandle& h_parent)
 
 namespace {
 struct GraphNodeBox {
-    CUgraphNode resource;
+    mutable CUgraphNode resource;
     GraphHandle h_graph;
 };
 }  // namespace
@@ -978,6 +978,12 @@ GraphHandle graph_node_get_graph(const GraphNodeHandle& h) noexcept {
     return h ? get_box(h)->h_graph : GraphHandle{};
 }
 
+void invalidate_graph_node_handle(const GraphNodeHandle& h) noexcept {
+    if (h) {
+        get_box(h)->resource = nullptr;
+    }
+}
+
 // ============================================================================
 // Graphics Resource Handles
 // ============================================================================

cuda_core/cuda/core/_cpp/resource_handles.hpp

@@ -415,6 +415,9 @@ GraphNodeHandle create_graph_node_handle(CUgraphNode node, const GraphHandle& h_
 // Extract the owning graph handle from a node handle.
 GraphHandle graph_node_get_graph(const GraphNodeHandle& h) noexcept;
 
+// Zero the CUgraphNode resource inside the handle, marking it invalid.
+void invalidate_graph_node_handle(const GraphNodeHandle& h) noexcept;
+
 // ============================================================================
 // Graphics resource handle functions
 // ============================================================================

cuda_core/cuda/core/_graph/_graph_def/_graph_node.pyx

@@ -48,6 +48,7 @@ from cuda.core._resource_handles cimport (
     create_graph_handle_ref,
     create_graph_node_handle,
     graph_node_get_graph,
+    invalidate_graph_node_handle,
 )
 from cuda.core._utils.cuda_utils cimport HANDLE_RETURN, _parse_fill_value
 
@@ -123,16 +124,27 @@ cdef class GraphNode:
         """
         return as_py(self._h_node)
 
-    def discard(self):
-        """Discard this node and remove all its edges from the parent graph.
+    @property
+    def is_valid(self):
+        """Whether this node is valid (not destroyed).
 
-        Safe to call on an already-discarded node (no-op).
+        Returns ``False`` after :meth:`destroy` has been called.
+        """
+        return as_intptr(self._h_node) != 0
+
+    def destroy(self):
+        """Destroy this node and remove all its edges from the parent graph.
+
+        After this call, :attr:`is_valid` returns ``False`` and the node
+        cannot be re-added to any graph.  Safe to call on an
+        already-destroyed node (no-op).
         """
-        if self not in self.graph.nodes():
-            return
         cdef cydriver.CUgraphNode node = as_cu(self._h_node)
+        if node == NULL:
+            return
         with nogil:
             HANDLE_RETURN(cydriver.cuGraphDestroyNode(node))
+        invalidate_graph_node_handle(self._h_node)
 
     @property
     def pred(self):

cuda_core/cuda/core/_resource_handles.pxd

@@ -186,6 +186,7 @@ cdef GraphHandle create_graph_handle_ref(cydriver.CUgraph graph, const GraphHand
 # Graph node handles
 cdef GraphNodeHandle create_graph_node_handle(cydriver.CUgraphNode node, const GraphHandle& h_graph) except+ nogil
 cdef GraphHandle graph_node_get_graph(const GraphNodeHandle& h) noexcept nogil
+cdef void invalidate_graph_node_handle(const GraphNodeHandle& h) noexcept nogil
 
 # Graphics resource handles
 cdef GraphicsResourceHandle create_graphics_resource_handle(

cuda_core/cuda/core/_resource_handles.pyx

@@ -159,6 +159,8 @@ cdef extern from "_cpp/resource_handles.hpp" namespace "cuda_core":
         cydriver.CUgraphNode node, const GraphHandle& h_graph) except+ nogil
     GraphHandle graph_node_get_graph "cuda_core::graph_node_get_graph" (
         const GraphNodeHandle& h) noexcept nogil
+    void invalidate_graph_node_handle "cuda_core::invalidate_graph_node_handle" (
+        const GraphNodeHandle& h) noexcept nogil
 
     # Graphics resource handles
     GraphicsResourceHandle create_graphics_resource_handle "cuda_core::create_graphics_resource_handle" (

cuda_core/tests/graph/test_graphdef_mutation.py

@@ -9,7 +9,6 @@
 from helpers.graph_kernels import compile_parallel_kernels
 from helpers.marks import requires_module
 
-from cuda.bindings import driver
 from cuda.core import Device, LaunchConfig, LegacyPinnedMemoryResource
 from cuda.core._graph._graph_def import GraphDef, KernelNode, MemsetNode
 from cuda.core._utils.cuda_utils import CUDAError
@@ -153,11 +152,11 @@ def test_baseline(self, init_cuda):
         assert rig.nodes == rig.initial_nodes
         rig.close()
 
-    def test_discard_a1(self, init_cuda):
-        """Discard a1 (creates a race on arm a). Arm b yields the expected
+    def test_destroy_a1(self, init_cuda):
+        """Destroy a1 (creates a race on arm a). Arm b yields the expected
         value, and the final step is correctly ordered after b completes."""
         rig = YRig()
-        rig.a[1].discard()
+        rig.a[1].destroy()
         rig.run()
         _, b_exp, _ = rig.expected_output
         assert rig.B_out == b_exp
@@ -167,10 +166,10 @@ def test_discard_a1(self, init_cuda):
         assert rig.nodes == rig.initial_nodes - {a1}
         rig.close()
 
-    def test_discard_a2(self, init_cuda):
-        """Discard a2, connect a1--r"""
+    def test_destroy_a2(self, init_cuda):
+        """Destroy a2, connect a1--r"""
         rig = YRig()
-        rig.a[2].discard()
+        rig.a[2].destroy()
         rig.a[1].succ.add(rig.r)
         rig.A_OPS.pop()
         rig.run()
@@ -180,11 +179,11 @@ def test_discard_a2(self, init_cuda):
         assert rig.nodes == rig.initial_nodes - {a2}
         rig.close()
 
-    def test_discard_joint(self, init_cuda):
+    def test_destroy_joint(self, init_cuda):
         """Remove the joining node and instead add edges directly to r."""
         rig = YRig()
         _, _, a2, _, b1, j, r = rig.a + rig.b + [rig.j, rig.r]
-        j.discard()
+        j.destroy()
         r.pred = {a2, b1}
         rig.run()
         assert rig.output == rig.expected_output
@@ -266,8 +265,8 @@ def test_adjacency_set_property_setter(init_cuda):
     assert hub.pred == set()
 
 
-def test_discarded_node(init_cuda):
-    """Test uses of discarded nodes."""
+def test_destroyed_node(init_cuda):
+    """Test that destroy() invalidates a node."""
     mr = LegacyPinnedMemoryResource()
     buf = mr.allocate(4)
     arr = np.from_dlpack(buf).view(np.int32)
@@ -278,25 +277,34 @@ def test_discarded_node(init_cuda):
     a = g.memset(ptr, 0, 4)
     b = a.memset(ptr, 42, 4)
 
+    assert a.is_valid
+    assert b.is_valid
     assert b in g.nodes()
     assert (a, b) in g.edges()
 
-    b.discard()
+    b.destroy()
 
-    # b is removed from the graph but still usable
+    assert not b.is_valid
     assert b not in g.nodes()
     assert (a, b) not in g.edges()
+
+    # Python object is invalid but using it does not crash.
     assert isinstance(b, MemsetNode)
-    assert b.type == driver.CUgraphNodeType.CU_GRAPH_NODE_TYPE_KERNEL
+    assert b.type is None
     assert b.pred == set()
     assert b.succ == set()
-    assert b.handle != 0
-    assert b.dptr == ptr
-    assert b.value == 42
-    assert b.width == 4
+    assert b.handle is None
+    assert b.dptr == ptr  # tolerable
+    assert b.value == 42  # tolerable
+    assert b.width == 4  # tolerable
+
+    # Adding an edge to a destroyed node fails.
+    with pytest.raises(CUDAError):
+        a.succ.add(b)
 
-    # Repeated discard succeeds quietly.
-    b.discard()
+    # Repeated destroy succeeds quietly.
+    b.destroy()
+    assert not b.is_valid
 
 
 def test_add_wrong_type(init_cuda):