Skip to content

Commit df550c9

Browse files
feat(cuda.core): add synchronization_policy to LaunchConfig
Expose CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY through LaunchConfig so cuda.core users can set per-launch CPU wait policies without dropping to cuda.bindings.driver. Adds SynchronizationPolicyType and tests for native attribute mapping and real kernel launches. Closes NVIDIA#2628. Co-authored-by: Cursor <[email protected]> Signed-off-by: Omar Atie <[email protected]>
1 parent db28018 commit df550c9

6 files changed

Lines changed: 175 additions & 4 deletions

File tree

‎cuda_core/cuda/core/_launch_config.pxd‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ cdef class LaunchConfig:
1616
public int shmem_size
1717
public bint is_cooperative
1818
public bint programmatic_stream_serialization
19+
public object synchronization_policy
1920

2021
vector[cydriver.CUlaunchAttribute] _attrs
2122
object __weakref__

‎cuda_core/cuda/core/_launch_config.pyi‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ from __future__ import annotations
44

55
from typing import Any
66

7+
from cuda.core.typing import SynchronizationPolicyType
8+
79

810
class LaunchConfig:
911
"""Customizable launch options.
@@ -39,9 +41,12 @@ class LaunchConfig:
3941
Whether to allow programmatic stream serialization (PDL). When True,
4042
the kernel may overlap with a previous kernel in the same stream that
4143
signals completion via programmatic means.
44+
synchronization_policy : SynchronizationPolicyType | None, optional
45+
CPU wait policy applied when synchronizing the launch stream after this
46+
kernel. Maps to ``CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY``.
4247
"""
4348

44-
def __init__(self, grid: int | tuple[int, ...] | None=None, cluster: int | tuple[int, ...] | None=None, block: int | tuple[int, ...] | None=None, shmem_size: int | None=None, is_cooperative: bool=False, programmatic_stream_serialization: bool=False) -> None:
49+
def __init__(self, grid: int | tuple[int, ...] | None=None, cluster: int | tuple[int, ...] | None=None, block: int | tuple[int, ...] | None=None, shmem_size: int | None=None, is_cooperative: bool=False, programmatic_stream_serialization: bool=False, synchronization_policy: SynchronizationPolicyType | int | None=None) -> None:
4550
"""Initialize LaunchConfig with validation.
4651
4752
Parameters
@@ -58,6 +63,8 @@ class LaunchConfig:
5863
Whether to launch as cooperative kernel (default: False)
5964
programmatic_stream_serialization : bool, optional
6065
Whether to allow programmatic stream serialization / PDL (default: False)
66+
synchronization_policy : SynchronizationPolicyType | None, optional
67+
CPU wait policy for synchronizing the launch stream (default: None)
6168
"""
6269

6370
def _identity(self) -> tuple[Any, ...]:
@@ -71,7 +78,7 @@ class LaunchConfig:
7178

7279
def __hash__(self) -> int:
7380
...
74-
_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative', 'programmatic_stream_serialization')
81+
_LAUNCH_CONFIG_ATTRS = ('grid', 'cluster', 'block', 'shmem_size', 'is_cooperative', 'programmatic_stream_serialization', 'synchronization_policy')
7582
__all__ = ['LaunchConfig']
7683

7784
def _to_native_launch_config(config: LaunchConfig) -> object:

‎cuda_core/cuda/core/_launch_config.pyx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,32 @@ _LAUNCH_CONFIG_ATTRS = (
2020
'shmem_size',
2121
'is_cooperative',
2222
'programmatic_stream_serialization',
23+
'synchronization_policy',
2324
)
2425

26+
27+
cdef object _validate_synchronization_policy(object policy):
28+
from cuda.core.typing import SynchronizationPolicyType
29+
30+
if policy is None:
31+
return None
32+
if isinstance(policy, SynchronizationPolicyType):
33+
return policy
34+
try:
35+
value = int(policy)
36+
except (TypeError, ValueError) as exc:
37+
raise TypeError(
38+
"LaunchConfig.synchronization_policy must be a SynchronizationPolicyType, "
39+
f"cuda.bindings.driver.CUsynchronizationPolicy, or int; got {type(policy).__name__}"
40+
) from exc
41+
try:
42+
return SynchronizationPolicyType(value)
43+
except ValueError as exc:
44+
raise ValueError(
45+
f"LaunchConfig.synchronization_policy must be one of "
46+
f"{[member.name for member in SynchronizationPolicyType]}; got {policy!r}"
47+
) from exc
48+
2549
__all__ = ['LaunchConfig']
2650

2751

@@ -59,6 +83,9 @@ cdef class LaunchConfig:
5983
Whether to allow programmatic stream serialization (PDL). When True,
6084
the kernel may overlap with a previous kernel in the same stream that
6185
signals completion via programmatic means.
86+
synchronization_policy : SynchronizationPolicyType | None, optional
87+
CPU wait policy applied when synchronizing the launch stream after this
88+
kernel. Maps to ``CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY``.
6289
"""
6390

6491
# TODO: expand LaunchConfig to include other attributes
@@ -72,6 +99,7 @@ cdef class LaunchConfig:
7299
shmem_size: int | None = None,
73100
is_cooperative: bool = False,
74101
programmatic_stream_serialization: bool = False,
102+
synchronization_policy: object = None,
75103
) -> None:
76104
"""Initialize LaunchConfig with validation.
77105

@@ -89,6 +117,8 @@ cdef class LaunchConfig:
89117
Whether to launch as cooperative kernel (default: False)
90118
programmatic_stream_serialization : bool, optional
91119
Whether to allow programmatic stream serialization / PDL (default: False)
120+
synchronization_policy : SynchronizationPolicyType | None, optional
121+
CPU wait policy for synchronizing the launch stream (default: None)
92122
"""
93123
# Convert and validate grid and block dimensions
94124
self.grid = cast_to_3_tuple("LaunchConfig.grid", grid)
@@ -116,6 +146,7 @@ cdef class LaunchConfig:
116146

117147
self.is_cooperative = is_cooperative
118148
self.programmatic_stream_serialization = programmatic_stream_serialization
149+
self.synchronization_policy = _validate_synchronization_policy(synchronization_policy)
119150

120151
if self.is_cooperative and not Device().properties.cooperative_launch:
121152
raise CUDAError("cooperative kernels are not supported on this device")
@@ -169,6 +200,11 @@ cdef class LaunchConfig:
169200
attr.value.programmaticStreamSerializationAllowed = 1
170201
self._attrs.push_back(attr)
171202

203+
if self.synchronization_policy is not None:
204+
attr.id = cydriver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY
205+
attr.value.syncPolicy = <cydriver.CUsynchronizationPolicy>int(self.synchronization_policy)
206+
self._attrs.push_back(attr)
207+
172208
drv_cfg.numAttrs = self._attrs.size()
173209
drv_cfg.attrs = self._attrs.data()
174210

@@ -230,6 +266,12 @@ cpdef object _to_native_launch_config(LaunchConfig config):
230266
attr.value.programmaticStreamSerializationAllowed = 1
231267
attrs.append(attr)
232268

269+
if config.synchronization_policy is not None:
270+
attr = driver.CUlaunchAttribute()
271+
attr.id = driver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY
272+
attr.value.syncPolicy = int(config.synchronization_policy)
273+
attrs.append(attr)
274+
233275
drv_cfg.numAttrs = len(attrs)
234276
drv_cfg.attrs = attrs
235277

‎cuda_core/cuda/core/typing.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
"""Public type aliases, protocols, and enumerations used in cuda.core API signatures."""
66

77
import sys
8+
from enum import IntEnum
89
from typing import TYPE_CHECKING
910
from typing import Literal as _Literal
1011
from typing import TypeAlias as _TypeAlias
@@ -47,6 +48,7 @@ class StrEnum(str, Enum):
4748
"ProcessStateType",
4849
"ReadModeType",
4950
"SourceCodeType",
51+
"SynchronizationPolicyType",
5052
"VirtualMemoryAccessType",
5153
"VirtualMemoryAllocationType",
5254
"VirtualMemoryGranularityType",
@@ -124,6 +126,23 @@ class PCHStatusType(StrEnum):
124126
FAILED = "failed"
125127

126128

129+
class SynchronizationPolicyType(IntEnum):
130+
"""CPU wait policy for host-side stream synchronization after a launch.
131+
132+
Maps to ``CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY``.
133+
134+
* ``AUTO`` — inherit the stream's synchronization policy.
135+
* ``SPIN`` — busy-wait on the CPU (lowest latency).
136+
* ``YIELD`` — yield the CPU while waiting.
137+
* ``BLOCKING_SYNC`` — block in the OS scheduler while waiting.
138+
"""
139+
140+
AUTO = 0
141+
SPIN = 1
142+
YIELD = 2
143+
BLOCKING_SYNC = 3
144+
145+
127146
class GraphConditionalType(StrEnum):
128147
"""Conditional node flavor for :class:`~cuda.core.graph.GraphBuilder`.
129148

‎cuda_core/tests/test_launcher.py‎

Lines changed: 103 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
cp = None
1414
import numpy as np
1515
import pytest
16+
from cuda.bindings import driver
1617
from conftest import skipif_need_cuda_headers
1718

1819
from cuda.core import (
@@ -26,7 +27,7 @@
2627
)
2728
from cuda.core._memory._legacy import _SynchronousMemoryResource
2829
from cuda.core._utils.cuda_utils import CUDAError
29-
from cuda.core.typing import ObjectCodeFormatType, SourceCodeType
30+
from cuda.core.typing import ObjectCodeFormatType, SourceCodeType, SynchronizationPolicyType
3031

3132

3233
def test_launch_config_init(init_cuda):
@@ -202,6 +203,107 @@ def test_to_native_launch_config_pdl():
202203
)
203204

204205

206+
@pytest.mark.parametrize(
207+
("policy", "expected_value"),
208+
[
209+
(SynchronizationPolicyType.AUTO, driver.CUsynchronizationPolicy.CU_SYNC_POLICY_AUTO),
210+
(SynchronizationPolicyType.SPIN, driver.CUsynchronizationPolicy.CU_SYNC_POLICY_SPIN),
211+
(SynchronizationPolicyType.YIELD, driver.CUsynchronizationPolicy.CU_SYNC_POLICY_YIELD),
212+
(
213+
SynchronizationPolicyType.BLOCKING_SYNC,
214+
driver.CUsynchronizationPolicy.CU_SYNC_POLICY_BLOCKING_SYNC,
215+
),
216+
(driver.CUsynchronizationPolicy.CU_SYNC_POLICY_SPIN, driver.CUsynchronizationPolicy.CU_SYNC_POLICY_SPIN),
217+
],
218+
)
219+
def test_to_native_launch_config_synchronization_policy(policy, expected_value):
220+
"""LaunchConfig.synchronization_policy maps to CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY."""
221+
from cuda.core._launch_config import _to_native_launch_config
222+
223+
config = LaunchConfig(grid=1, block=1, synchronization_policy=policy)
224+
assert config.synchronization_policy is SynchronizationPolicyType(int(expected_value))
225+
226+
native = _to_native_launch_config(config)
227+
assert native.numAttrs == 1
228+
attr = native.attrs[0]
229+
assert attr.id == driver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY
230+
assert attr.value.syncPolicy == expected_value
231+
232+
233+
def test_launch_config_synchronization_policy_default():
234+
config = LaunchConfig(grid=1, block=1)
235+
assert config.synchronization_policy is None
236+
237+
from cuda.core._launch_config import _to_native_launch_config
238+
239+
native = _to_native_launch_config(config)
240+
assert native.numAttrs == 0
241+
242+
243+
@pytest.mark.parametrize("invalid_policy", ["spin", -1, 99])
244+
def test_launch_config_synchronization_policy_invalid(invalid_policy):
245+
with pytest.raises((TypeError, ValueError)):
246+
LaunchConfig(grid=1, block=1, synchronization_policy=invalid_policy)
247+
248+
249+
def test_to_native_launch_config_synchronization_policy_with_cooperative(monkeypatch):
250+
"""synchronization_policy can be combined with other launch attributes."""
251+
from cuda.core import _launch_config as _lc_mod
252+
from cuda.core._launch_config import _to_native_launch_config
253+
254+
class _FakeProps:
255+
cooperative_launch = True
256+
257+
class _FakeDev:
258+
properties = _FakeProps()
259+
260+
monkeypatch.setattr(_lc_mod, "Device", lambda: _FakeDev())
261+
262+
config = LaunchConfig(
263+
grid=1,
264+
block=1,
265+
is_cooperative=True,
266+
synchronization_policy=SynchronizationPolicyType.SPIN,
267+
)
268+
native = _to_native_launch_config(config)
269+
assert native.numAttrs == 2
270+
attr_ids = {attr.id for attr in native.attrs}
271+
assert driver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_COOPERATIVE in attr_ids
272+
assert driver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY in attr_ids
273+
sync_attrs = [
274+
attr
275+
for attr in native.attrs
276+
if attr.id == driver.CUlaunchAttributeID.CU_LAUNCH_ATTRIBUTE_SYNCHRONIZATION_POLICY
277+
]
278+
assert len(sync_attrs) == 1
279+
assert sync_attrs[0].value.syncPolicy == driver.CUsynchronizationPolicy.CU_SYNC_POLICY_SPIN
280+
281+
282+
@pytest.mark.parametrize(
283+
"policy",
284+
[
285+
SynchronizationPolicyType.AUTO,
286+
SynchronizationPolicyType.SPIN,
287+
SynchronizationPolicyType.YIELD,
288+
SynchronizationPolicyType.BLOCKING_SYNC,
289+
],
290+
)
291+
def test_launch_with_synchronization_policy(init_cuda, policy):
292+
"""Driver accepts per-launch synchronization policies on a real kernel launch."""
293+
dev = Device()
294+
dev.set_current()
295+
stream = dev.create_stream()
296+
297+
code = 'extern "C" __global__ void noop() {}'
298+
program = Program(code, SourceCodeType.CXX)
299+
mod = program.compile(ObjectCodeFormatType.CUBIN)
300+
ker = mod.get_kernel("noop")
301+
302+
config = LaunchConfig(grid=1, block=1, synchronization_policy=policy)
303+
launch(stream, config, ker)
304+
stream.sync()
305+
306+
205307
@skipif_need_cuda_headers
206308
def test_pdl_primary_secondary_overlap_same_stream():
207309
"""Primary + secondary PDL launch on one stream can overlap on Hopper+.

‎cuda_core/tests/test_object_protocols.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -685,7 +685,7 @@ def sample_switch_node_alt(sample_graphdef):
685685
"sample_launch_config",
686686
r"LaunchConfig\(grid=\(\d+, \d+, \d+\), cluster=.+, block=\(\d+, \d+, \d+\), "
687687
r"shmem_size=\d+, is_cooperative=(?:True|False), "
688-
r"programmatic_stream_serialization=(?:True|False)\)",
688+
r"programmatic_stream_serialization=(?:True|False), synchronization_policy=(?:None|SynchronizationPolicyType\.\w+)\)",
689689
),
690690
("sample_kernel", r"<Kernel handle=0x[0-9a-f]+>"),
691691
# ObjectCode variations (by code_type)

0 commit comments

Comments
 (0)