Add GraphDef.empty(), stack-buffer query optimization, and registry test

- Add GraphDef.empty() for creating entry-point empty nodes; replace
  all no-arg join() calls on GraphDef with empty() in tests.
- Optimize _AdjacencySetCore.query() to use a 16-element stack buffer,
  matching the contains() optimization.
- Add test_registry_cleanup exercising destroy(), graph deletion, and
  weak-reference cleanup of the node registry.

Made-with: Cursor

Author: Andy-Jost

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

@@ -143,11 +143,14 @@ cdef class _AdjacencySetCore:
         cdef cydriver.CUgraphNode c_node = as_cu(self._h_node)
         if c_node == NULL:
             return []
-        cdef size_t count = 0
+        cdef cydriver.CUgraphNode buf[16]
+        cdef size_t count = 16
+        cdef size_t i
         with nogil:
-            HANDLE_RETURN(self._query_fn(c_node, NULL, &count))
-        if count == 0:
-            return []
+            HANDLE_RETURN(self._query_fn(c_node, buf, &count))
+        if count <= 16:
+            return [GraphNode._create(self._h_graph, buf[i])
+                    for i in range(count)]
         cdef vector[cydriver.CUgraphNode] nodes_vec
         nodes_vec.resize(count)
         with nogil:
@@ -166,19 +169,23 @@ cdef class _AdjacencySetCore:
         cdef size_t i
         with nogil:
             HANDLE_RETURN(self._query_fn(c_node, buf, &count))
+
+        # Fast path for small sets.
         if count <= 16:
             for i in range(count):
                 if buf[i] == target:
                     return True
-        else:
-            cdef vector[cydriver.CUgraphNode] nodes_vec
-            nodes_vec.resize(count)
-            with nogil:
-                HANDLE_RETURN(self._query_fn(c_node, nodes_vec.data(), &count))
-            assert count == nodes_vec.size()
-            for i in range(count):
-                if nodes_vec[i] == target:
-                    return True
+            return False
+
+        # Fallback for large sets.
+        cdef vector[cydriver.CUgraphNode] nodes_vec
+        nodes_vec.resize(count)
+        with nogil:
+            HANDLE_RETURN(self._query_fn(c_node, nodes_vec.data(), &count))
+        assert count == nodes_vec.size()
+        for i in range(count):
+            if nodes_vec[i] == target:
+                return True
         return False
 
     cdef Py_ssize_t count(self):

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

@@ -159,6 +159,16 @@ cdef class GraphDef:
         """
         return self._entry.launch(config, kernel, *args)
 
+    def empty(self) -> "EmptyNode":
+        """Add an entry-point empty node (no dependencies).
+
+        Returns
+        -------
+        EmptyNode
+            A new EmptyNode with no dependencies.
+        """
+        return self._entry.join()
+
     def join(self, *nodes) -> "EmptyNode":
         """Create an empty node that depends on all given nodes.
 

cuda_core/tests/graph/test_graphdef.py

@@ -703,7 +703,7 @@ def test_identity_preservation(init_cuda):
     """Round-trips through nodes(), edges(), and pred/succ return extant
     objects rather than duplicates."""
     g = GraphDef()
-    a = g.join()
+    a = g.empty()
     b = a.join()
 
     # nodes()
@@ -724,6 +724,49 @@ def test_identity_preservation(init_cuda):
     assert b2 is b
 
 
+def test_registry_cleanup(init_cuda):
+    """Node registry entries are removed on destroy() and graph teardown."""
+    import gc
+    from cuda.core._graph._graph_def._graph_node import _node_registry
+
+    def registered(node):
+        return any(v is node for v in _node_registry.values())
+
+    gc.collect()
+    assert len(_node_registry) == 0
+
+    g = GraphDef()
+    a = g.empty()
+    b = g.empty()
+    c = g.empty()
+
+    assert len(_node_registry) == 3
+    assert registered(a)
+    assert registered(b)
+    assert registered(c)
+
+    a.destroy()
+    assert len(_node_registry) == 2
+    assert not registered(a)
+    assert registered(b)
+    assert registered(c)
+
+    del g
+    gc.collect()
+    assert len(_node_registry) == 2
+    assert registered(b)
+    assert registered(c)
+
+    b.destroy()
+    assert len(_node_registry) == 1
+    assert not registered(b)
+    assert registered(c)
+
+    del c
+    gc.collect()
+    assert len(_node_registry) == 0
+
+
 # =============================================================================
 # GraphDef basics
 # =============================================================================

cuda_core/tests/graph/test_graphdef_errors.py

@@ -101,10 +101,10 @@ def test_condition_from_different_graph(init_cuda):
 # =============================================================================
 
 
-def test_join_no_extra_nodes(init_cuda):
-    """join() from entry with no extra nodes creates a single empty node."""
+def test_empty_node(init_cuda):
+    """empty() creates a single entry-point empty node."""
     g = GraphDef()
-    joined = g.join()
+    joined = g.empty()
     assert isinstance(joined, EmptyNode)
     assert len(g.nodes()) == 1
 

cuda_core/tests/graph/test_graphdef_mutation.py

@@ -211,16 +211,16 @@ def test_insert_b(self, init_cuda):
 def test_adjacency_set_interface(init_cuda):
     """Exercise every MutableSet method on AdjacencySetProxy."""
     g = GraphDef()
-    hub = g.join()
-    items = [g.join() for _ in range(5)]
+    hub = g.empty()
+    items = [g.empty() for _ in range(5)]
     assert_mutable_set_interface(hub.succ, items)
 
 
 def test_adjacency_set_pred_direction(init_cuda):
     """Verify that pred works symmetrically with succ."""
     g = GraphDef()
-    target = g.join()
-    x, y, z = (g.join() for _ in range(3))
+    target = g.empty()
+    x, y, z = (g.empty() for _ in range(3))
 
     pred = target.pred
     assert pred == set()
@@ -242,8 +242,8 @@ def test_adjacency_set_pred_direction(init_cuda):
 def test_adjacency_set_property_setter(init_cuda):
     """Verify that assigning to node.pred or node.succ replaces all edges."""
     g = GraphDef()
-    hub = g.join()
-    a, b, c = (g.join() for _ in range(3))
+    hub = g.empty()
+    a, b, c = (g.empty() for _ in range(3))
 
     hub.succ = {a, b}
     assert hub.succ == {a, b}
@@ -310,7 +310,7 @@ def test_destroyed_node(init_cuda):
 def test_add_wrong_type(init_cuda):
     """Adding a non-GraphNode raises TypeError."""
     g = GraphDef()
-    node = g.join()
+    node = g.empty()
     with pytest.raises(TypeError, match="expected GraphNode"):
         node.succ.add("not a node")
     with pytest.raises(TypeError, match="expected GraphNode"):
@@ -321,16 +321,16 @@ def test_cross_graph_edge(init_cuda):
     """Adding an edge to a node from a different graph raises CUDAError."""
     g1 = GraphDef()
     g2 = GraphDef()
-    a = g1.join()
-    b = g2.join()
+    a = g1.empty()
+    b = g2.empty()
     with pytest.raises(CUDAError):
         a.succ.add(b)
 
 
 def test_self_edge(init_cuda):
     """Adding a self-edge raises CUDAError."""
     g = GraphDef()
-    node = g.join()
+    node = g.empty()
     with pytest.raises(CUDAError):
         node.succ.add(node)