dpctl C API

dpctl core classes are implemented in Cython. C declarations for Python objects corresponding to these classes, as well as their Python types are generated by Cython.

Exported typedefs

struct PySyclDeviceObject
struct PySyclDeviceType
struct PySyclContextObject
struct PySyclContextType
struct PySyclQueueObject
struct PySyclQueueType
struct PySyclEventObject
struct PySyclEventType
struct Py_MemoryObject
struct Py_MemoryType
struct PySyclKernelObject
struct PySyclKernelType
struct PySyclProgramObject
struct PySyclProgramType

To check whether a particular Python object is an instance of dpctl.SyclQueue:

Check if an object is of type PySyclQueueType
#include "Python.h"
#include "dpctl_capi.h"

int PySyclQueue_Check(PyObject *o) {
    return PyObject_TypeCheck(o, &PySyclQueueType);
}

API for PySyclDeviceObject

DPCTLSyclDeviceRef SyclDevice_GetDeviceRef(struct PySyclDeviceObject *o)
Parameters:

  • o – Input object

Returns:

borrowed instance of DPCTLSyclDeviceRef

struct PySyclDeviceObject *SyclDevice_Make(DPCTLSyclDeviceRef DRef)
Parameters:

  • DRef – instance of DPCTLSyclDeviceRef

Returns:

new Python object of type PySyclDeviceType

Note that function does not change the ownership of the DRef instance and the caller remains responsible for freeing DRef as appropriate.

API for PySyclContextObject

DPCTLSyclContextRef SyclContext_GetContextRef(struct PySyclContextObject *o)
Parameters:

  • o – Input object

Returns:

borrowed instance of DPCTLSyclContextRef

struct PySyclContextObject *SyclContext_Make(DPCTLSyclContextRef CRef)
Parameters:

  • CRef – instance of DPCTLSyclContextRef

Returns:

new Python object of type PySyclContextType

Note that function does not change the ownership of the CRef instance and the caller remains responsible for freeing CRef as appropriate.

API for PySyclQueueObject

DPCTLSyclQueueRef SyclQueue_GetQueueRef(struct PySyclQueueObject *o)
Parameters:

  • o – Input object

Returns:

borrowed instance of DPCTLSyclQueueRef

struct PySyclQueueObject *SyclQueue_Make(DPCTLSyclQueueRef QRef)
Parameters:

  • QRef – instance of DPCTLSyclQueueRef

Returns:

new Python object of type PySyclQueueType

Note that function does not change the ownership of the QRef instance and the caller remains responsible for freeing QRef as appropriate.

API for PySyclEventObject

DPCTLSyclEventRef SyclEvent_GetEventRef(struct PySyclEventObject *o)
Parameters:

  • o – Input object

Returns:

borrowed instance of DPCTLSyclEventRef

struct PySyclEventObject *SyclEvent_Make(DPCTLSyclEventRef ERef)
Parameters:

  • ERef – instance of DPCTLSyclEventRef

Returns:

new Python object of type PySyclEventType

Note that function does not change the ownership of the ERef instance and the caller remains responsible for freeing ERef as appropriate.

API for Py_MemoryObject

DPCTLSyclUSMRef Memory_GetUsmPointer(struct Py_MemoryObject *o)
Parameters:

  • o – Input object

Returns:

Opaque pointer to USM allocation represented by Python object.

DPCTLSyclContextRef Memory_GetSyclContext(struct Py_MemoryObject *o)
Parameters:

  • o – Input object

Returns:

Returns borrowed instance of PySyclContextRef corresponding to sycl::context to which USM allocation represented by input Python object is bound.

DPCTLSyclQueueRef Memory_GetSyclQueue(struct Py_MemoryObject *o)
Parameters:

  • o – Input object

Returns:

Returns borrowed instance of PySyclQueueRef corresponding to sycl::queue associated with input Python object.

The sycl::queue uses the same sycl::context to which the USM allocation represented by input Python object is bound.

size_t Memory_GetNumBytes(struct Py_MemoryObject *o)
Parameters:

  • o – Input object

Returns:

Size of USM allocation in bytes.

struct Py_MemoryObject *Memory_Make(DPCTLSyclUSMRef ptr, size_t nbytes, DPCTLSyclQueueRef QRef, PyObject *owner)
Parameters:

  • ptr – Opaque pointer in unified address space

  • nbytes – The size of allocation in bytes

  • QRef – instance of PySyclQueueRef corresponding to sycl::queue to be associated with this allocation

  • owner – Python object instance whose deleter triggers freeing of this USM allocation. Specify owner=None to pass ownership to created Python memory object, which will use sycl::free(ptr, sycl_queue) for deallocation.

void *Memory_GetOpaquePointer(struct Py_MemoryObject *o)
Parameters:

  • o – Input object

Returns:

Returns opaque pointer to std::shared_ptr<void> which manages the USM allocation, or a nullptr if the USM allocation represented by o is not managed by the smart pointer.

API for PySyclKernelObject

DPCTLSyclKernelRef SyclKernel_GetKernelRef(struct PySyclKernelObject *krn)
Parameters:

  • krn – Input object

Returns:

borrowed instance of DPCTLSyclKernelRef corresponding to sycl::kernel

struct PySyclKernelObject *SyclKernel_Make(DPCTLSyclKernelRef KRef)
Parameters:

  • KRef – instance of DPCTLSyclKernelRef

Returns:

new Python object of type PySyclKernelType

Note that function does not change the ownership of the KRef instance and the caller remains responsible for freeing KRef as appropriate.

API for PySyclProgramObject

DPCTLSyclKernelBundleRef SyclProgram_GetKernelBundleRef(struct PySyclProgramObject *prog)
Parameters:

  • prog – Input object

Returns:

borrowed instance of DPCTLSyclKernelBundleRef corresponding to sycl::kernel_bundle<sycl::bundle_state::executable>

struct PySyclProgramObject *SyclProgram_Make(DPCTLSyclKernelBundleRef KBRef)
Parameters:

  • KBRef – instance of DPCTLSyclKernelBundleRef

Returns:

new Python object of type PySyclProgramType

Note that function does not change the ownership of the KBRef instance and the caller remains responsible for freeing KBRef as appropriate.