cuda.core: rename EventOptions to bare-adjective form (#1945)

Address review feedback on #1986: align EventOptions field names with
the convention used elsewhere in the API (option name = bare adjective,
property name = is_/uses_ prefix).

- EventOptions.enable_timing -> EventOptions.timing_enabled
  (matches Event.is_timing_enabled)
- EventOptions.use_blocking_sync -> EventOptions.blocking_sync
  (matches Event.uses_blocking_sync)

Same pattern as ipc_enabled / Event.is_ipc_enabled and
StreamOptions.nonblocking / Stream.is_nonblocking.

Made-with: Cursor

Author: Andy-Jost

cuda_core/cuda/core/_event.pyx

@@ -44,22 +44,22 @@ cdef class EventOptions:
 
     Attributes
     ----------
-    enable_timing : bool, optional
+    timing_enabled : bool, optional
         Event will record timing data. (Default to False)
-    use_blocking_sync : bool, optional
+    blocking_sync : bool, optional
         If True, the event uses blocking synchronization: a CPU
         thread that calls :meth:`Event.sync` blocks (yields) until
         the event has completed. Otherwise (the default), the CPU
         thread busy-waits until the event has completed.
         (Default to False)
     ipc_enabled : bool, optional
         Event will be suitable for interprocess use.
-        Note that enable_timing must be False. (Default to False)
+        Note that timing_enabled must be False. (Default to False)
 
     """
 
-    enable_timing: bool | None = False
-    use_blocking_sync: bool | None = False
+    timing_enabled: bool | None = False
+    blocking_sync: bool | None = False
     ipc_enabled: bool | None = False
 
 
@@ -79,8 +79,8 @@ cdef class Event:
 
         # To create events and record the timing:
         s = Device().create_stream()
-        e1 = Device().create_event({"enable_timing": True})
-        e2 = Device().create_event({"enable_timing": True})
+        e1 = Device().create_event({"timing_enabled": True})
+        e2 = Device().create_event({"timing_enabled": True})
         s.record(e1)
         # ... run some GPU works ...
         s.record(e2)
@@ -104,10 +104,10 @@ cdef class Event:
         cdef bint uses_blocking_sync = False
         cdef bint ipc_enabled = False
         self._ipc_descriptor = None
-        if not opts.enable_timing:
+        if not opts.timing_enabled:
             flags |= cydriver.CUevent_flags.CU_EVENT_DISABLE_TIMING
             timing_enabled = False
-        if opts.use_blocking_sync:
+        if opts.blocking_sync:
             flags |= cydriver.CUevent_flags.CU_EVENT_BLOCKING_SYNC
             uses_blocking_sync = True
         if opts.ipc_enabled:
@@ -167,7 +167,7 @@ cdef class Event:
                 if not self.is_timing_enabled or not other.is_timing_enabled:
                     explanation = (
                         "Both Events must be created with timing enabled in order to subtract them; "
-                        "use EventOptions(enable_timing=True) when creating both events."
+                        "use EventOptions(timing_enabled=True) when creating both events."
                     )
                 else:
                     explanation = (
@@ -244,7 +244,7 @@ cdef class Event:
     def sync(self):
         """Synchronize until the event completes.
 
-        If the event was created with ``use_blocking_sync=True``, the
+        If the event was created with ``blocking_sync=True``, the
         calling CPU thread blocks (yields) until the event has been
         completed by the device. Otherwise (the default) the CPU
         thread busy-waits until the event has completed.

cuda_core/docs/source/release/1.0.0-notes.rst

@@ -46,17 +46,10 @@ Breaking changes
 
   - ``LaunchConfig.cooperative_launch`` -> :attr:`LaunchConfig.is_cooperative`
     (also renames the constructor keyword argument).
-  - ``Event.is_timing_disabled`` -> :attr:`Event.is_timing_enabled` (boolean
-    polarity is flipped to avoid the double-negative form
-    ``not event.is_timing_disabled``).
-  - ``Event.is_sync_busy_waited`` -> :attr:`Event.uses_blocking_sync`. The
-    new name accurately describes the underlying ``CU_EVENT_BLOCKING_SYNC``
-    flag: when True, the calling CPU thread blocks (yields) on
-    :meth:`Event.sync` instead of busy-waiting. The previous name was
-    inverted with respect to its semantics.
-  - ``EventOptions.busy_waited_sync`` -> ``EventOptions.use_blocking_sync``
-    (constructor keyword argument and dataclass attribute), to match the
-    renamed :attr:`Event.uses_blocking_sync` property.
+  - ``Event.is_timing_disabled`` -> :attr:`Event.is_timing_enabled`.
+  - ``Event.is_sync_busy_waited`` -> :attr:`Event.uses_blocking_sync`.
+  - ``EventOptions.enable_timing`` -> ``EventOptions.timing_enabled``
+    and ``EventOptions.busy_waited_sync`` -> ``EventOptions.blocking_sync``.
 
 - Renamed graph allocation methods to match :meth:`MemoryResource.allocate` /
   :meth:`MemoryResource.deallocate`
@@ -115,10 +108,10 @@ Breaking changes
     ``if_else``, ``while_loop``, and ``switch`` methods (verb describing the
     control-flow construct, not an abbreviation of "condition") and matches
     Python's own ``if/then/else`` vocabulary.
-  - :class:`~graph.GraphCondition` now defines ``__int__`` returning the
-    underlying ``CUgraphConditionalHandle`` value, so a condition may be
-    passed directly as a kernel argument to ``launch()`` without first
-    extracting ``.handle``.
+  - A :class:`~graph.GraphCondition` may be passed directly as a kernel
+    argument to ``launch()``; the launcher unwraps it to the underlying
+    ``CUgraphConditionalHandle`` value. Previously, ``.handle`` had to be
+    extracted explicitly.
 
 
 Fixes and enhancements

cuda_core/tests/graph/test_graph_definition_integration.py

@@ -215,8 +215,8 @@ def _run_heat_graph(dev, k_heat, k_countdown, host_ptr):
     # Definitions
     g = GraphDefinition()
     condition = g.create_condition(default_value=1)
-    event_start = dev.create_event(EventOptions(enable_timing=True))
-    event_end = dev.create_event(EventOptions(enable_timing=True))
+    event_start = dev.create_event(EventOptions(timing_enabled=True))
+    event_end = dev.create_event(EventOptions(timing_enabled=True))
     results = {}
 
     def capture_result():

cuda_core/tests/graph/test_graph_definition_lifetime.py

@@ -174,7 +174,7 @@ def test_event_record_node_keeps_event_alive(init_cuda):
     g = GraphDefinition()
     alloc = g.allocate(1024)
 
-    event = dev.create_event(EventOptions(enable_timing=False))
+    event = dev.create_event(EventOptions(timing_enabled=False))
     node = alloc.record(event)
 
     del event
@@ -191,7 +191,7 @@ def test_event_wait_node_keeps_event_alive(init_cuda):
     g = GraphDefinition()
     alloc = g.allocate(1024)
 
-    event = dev.create_event(EventOptions(enable_timing=False))
+    event = dev.create_event(EventOptions(timing_enabled=False))
     node = alloc.wait(event)
 
     del event
@@ -206,7 +206,7 @@ def test_event_record_node_preserves_metadata(init_cuda):
     dev = Device()
     g = GraphDefinition()
 
-    event = dev.create_event(EventOptions(enable_timing=True, use_blocking_sync=True))
+    event = dev.create_event(EventOptions(timing_enabled=True, blocking_sync=True))
     node = g.record(event)
 
     reconstructed = node.event
@@ -221,7 +221,7 @@ def test_event_wait_node_preserves_metadata(init_cuda):
     dev = Device()
     g = GraphDefinition()
 
-    event = dev.create_event(EventOptions(enable_timing=False))
+    event = dev.create_event(EventOptions(timing_enabled=False))
     node = g.wait(event)
 
     reconstructed = node.event
@@ -235,7 +235,7 @@ def test_event_metadata_survives_gc(init_cuda):
     dev = Device()
     g = GraphDefinition()
 
-    event = dev.create_event(EventOptions(enable_timing=True, use_blocking_sync=True))
+    event = dev.create_event(EventOptions(timing_enabled=True, blocking_sync=True))
     node = g.record(event)
 
     del event
@@ -252,7 +252,7 @@ def test_event_survives_graph_instantiation_and_execution(init_cuda):
     dev = Device()
     g = GraphDefinition()
 
-    event = dev.create_event(EventOptions(enable_timing=False))
+    event = dev.create_event(EventOptions(timing_enabled=False))
     rec = g.record(event)
     rec.wait(event)
 
@@ -277,7 +277,7 @@ def test_event_survives_graph_clone_and_execution(init_cuda):
     dev = Device()
     g = GraphDefinition()
 
-    event = dev.create_event(EventOptions(enable_timing=False))
+    event = dev.create_event(EventOptions(timing_enabled=False))
     rec = g.record(event)
     rec.wait(event)
 

cuda_core/tests/memory_ipc/test_event_ipc.py

@@ -114,7 +114,7 @@ def test_event_is_monadic(ipc_device):
 
 @pytest.mark.flaky(reruns=2)
 @pytest.mark.parametrize(
-    "options", [{"ipc_enabled": True, "enable_timing": True}, EventOptions(ipc_enabled=True, enable_timing=True)]
+    "options", [{"ipc_enabled": True, "timing_enabled": True}, EventOptions(ipc_enabled=True, timing_enabled=True)]
 )
 def test_event_timing_disabled(ipc_device, options):
     """Check that IPC-enabled events cannot be created with timing enabled."""
@@ -131,10 +131,10 @@ class TestIpcEventProperties:
     """
 
     @pytest.mark.flaky(reruns=2)
-    @pytest.mark.parametrize("use_blocking_sync", [True, False])
+    @pytest.mark.parametrize("blocking_sync", [True, False])
     @pytest.mark.parametrize("use_options_cls", [True, False])
     @pytest.mark.parametrize("use_option_kw", [True, False])
-    def test_main(self, ipc_device, use_blocking_sync, use_options_cls, use_option_kw):
+    def test_main(self, ipc_device, blocking_sync, use_options_cls, use_option_kw):
         device = ipc_device
         stream = device.create_stream()
 
@@ -145,9 +145,9 @@ def test_main(self, ipc_device, use_blocking_sync, use_options_cls, use_option_k
 
         # Create an event and send it.
         options = (
-            EventOptions(ipc_enabled=True, use_blocking_sync=use_blocking_sync)
+            EventOptions(ipc_enabled=True, blocking_sync=blocking_sync)
             if use_options_cls
-            else {"ipc_enabled": True, "use_blocking_sync": use_blocking_sync}
+            else {"ipc_enabled": True, "blocking_sync": blocking_sync}
         )
         e = stream.record(options=options) if use_option_kw else stream.record(None, options)
         q_out.put(e)

cuda_core/tests/test_event.py

@@ -23,7 +23,7 @@ def test_event_init_disabled():
 
 @pytest.mark.skipif(Device().compute_capability.major < 7, reason="__nanosleep is only available starting Volta (sm70)")
 def test_timing_success(init_cuda):
-    options = EventOptions(enable_timing=True)
+    options = EventOptions(timing_enabled=True)
     device = Device()
     stream = device.create_stream()
 
@@ -49,27 +49,27 @@ def test_timing_success(init_cuda):
 
 
 def test_uses_blocking_sync(init_cuda):
-    options = EventOptions(enable_timing=False, use_blocking_sync=True)
+    options = EventOptions(timing_enabled=False, blocking_sync=True)
     stream = Device().create_stream()
     event = stream.record(options=options)
     assert event.uses_blocking_sync is True
 
-    options = EventOptions(enable_timing=False)
+    options = EventOptions(timing_enabled=False)
     stream = Device().create_stream()
     event = stream.record(options=options)
     assert event.uses_blocking_sync is False
 
 
 def test_sync(init_cuda):
-    options = EventOptions(enable_timing=False)
+    options = EventOptions(timing_enabled=False)
     stream = Device().create_stream()
     event = stream.record(options=options)
     event.sync()
     assert event.is_done is True
 
 
 def test_is_done(init_cuda):
-    options = EventOptions(enable_timing=False)
+    options = EventOptions(timing_enabled=False)
     stream = Device().create_stream()
     event = stream.record(options=options)
     # Without a sync, the captured work might not have yet completed
@@ -80,8 +80,8 @@ def test_is_done(init_cuda):
 def test_error_timing_disabled():
     device = Device()
     device.set_current()
-    enabled = EventOptions(enable_timing=True)
-    disabled = EventOptions(enable_timing=False)
+    enabled = EventOptions(timing_enabled=True)
+    disabled = EventOptions(timing_enabled=False)
     stream = device.create_stream()
 
     event1 = stream.record(options=enabled)
@@ -102,7 +102,7 @@ def test_error_timing_disabled():
 def test_error_timing_recorded():
     device = Device()
     device.set_current()
-    enabled = EventOptions(enable_timing=True)
+    enabled = EventOptions(timing_enabled=True)
     stream = device.create_stream()
 
     event1 = stream.record(options=enabled)
@@ -123,7 +123,7 @@ def test_error_timing_incomplete():
     device = Device()
     device.set_current()
     latch = LatchKernel(device)
-    enabled = EventOptions(enable_timing=True)
+    enabled = EventOptions(timing_enabled=True)
     stream = device.create_stream()
 
     event1 = stream.record(options=enabled)