Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (48 loc) · 1.69 KB

AGENTS.md

File metadata and controls

62 lines (48 loc) · 1.69 KB

dpctl/ - Core SYCL Bindings

Purpose

Python/Cython wrappers for SYCL runtime objects: Device, Queue, Context, Event, Platform.

Key Files

File Purpose
_sycl_device.pyx SyclDevice wrapping sycl::device
_sycl_queue.pyx SyclQueue wrapping sycl::queue
_sycl_context.pyx SyclContext wrapping sycl::context
_sycl_event.pyx SyclEvent wrapping sycl::event
_sycl_platform.pyx SyclPlatform wrapping sycl::platform
_sycl_device_factory.pyx Device enumeration and selection
_sycl_queue_manager.pyx Queue management utilities
_backend.pxd C API declarations from libsyclinterface
enum_types.py Python enums for SYCL types

Cython Conventions

Required Directives (after license header)

# distutils: language = c++
# cython: language_level=3
# cython: linetrace=True

Extension Type Pattern

cdef class SyclDevice:
    cdef DPCTLSyclDeviceRef _device_ref  # C reference

    def __dealloc__(self):
        if self._device_ref is not NULL:
            DPCTLDevice_Delete(self._device_ref)

    cdef DPCTLSyclDeviceRef get_device_ref(self):
        return self._device_ref

Key Rules

  • Store C references as _*_ref attributes
  • Always clean up in __dealloc__ with NULL check
  • Use with nogil: for blocking C calls
  • Check NULL before using C API returns

Exceptions

  • SyclDeviceCreationError
  • SyclQueueCreationError
  • SyclContextCreationError

cimport vs import

# cimport - C-level declarations (compile-time)
from ._backend cimport DPCTLSyclDeviceRef, DPCTLDevice_Create

# import - Python-level (runtime)
from . import _device_selection