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 PyUSMArrayObject
struct PyUSMArrayType
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 PyUSMArrayObject

char *UsmNDArray_GetData(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Pointer to array element referred to by all-zeros multi-index.

int UsmNDArray_GetNDim(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Number of indices required to uniquely specify element of this array

The returned value is also known as array dimensionality or array rank.

Py_ssize_t *UsmNDArray_GetShape(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Pointer to array of sizes of array along each dimension.

The array has at least as many elements as returned by UsmNDArray_GetNDim() applied to input object arr.

Py_ssize_t *UsmNDArray_GetStrides(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Pointer to array of strides of array along each dimension.

Returns:

NULL if array is C- or F-contiguous.

The array has at least as many elements as returned by UsmNDArray_GetNDim() applied to input object arr.

int UsmNDarray_GetTypenum(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

An integer encoding the type of array elements.

The encoding is consistent with that integral values corresponding to enums used by numpy. See NumPy Dtype C-API.

int UsmNDarray_GetElementSize(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Size of single element of the array in bytes.

int UsmNDarray_GetFlags(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

An integer encoding flags attribute of the array.

The flag encodes whether the array is C-contiguous, F-contiguous, whether it is read-only, or can be modified.

DPCTLSyclQueueRef UsmNDarray_GetQueueRef(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

A borrowed instance of DPCTLSyclQueueRef

The returned value corresponds to sycl::queue associated with underlying USM allocation.

Py_ssize_t UsmNDArray_GetOffset(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Offset of zero multi-index array element from the beginning of the USM allocation.

PyObject *UsmNDArray_GetUSMData(struct PyUSMArrayObject *arr)
Parameters:

  • arr – Input object

Returns:

Python memory object underlying input array arr.

void UsmNDArray_SetWritableFlag(struct PyUSMArrayObject *arr, int flag)
Parameters:

  • arr – Input object

  • flags – Whether to set writable flag of the array to read-only, or to writable.

Non-zero value of flag parameter sets the array flag bit to writable, a zero-value of flag parameter sets the flag bit of the array to read-only.

PyObject *UsmNDArray_MakeSimpleFromMemory(int nd, const Py_ssize_t *shape, int typenum, struct Py_MemoryObject *mobj, Py_ssize_t offset, char order)
Parameters:

  • nd – Dimensionality of array

  • shape – Array with array sizes for each dimension

  • typenum – Integer encoding type of array elements

  • mobj – Python USM memory object

  • offset – Offset to zero multi-index array element from the beginning of USM allocation

  • order – Memory layout of the array (‘C’ for C-contiguous or row-major layout, ‘F’ for F-contiguous or column-major layout)

Returns:

usm_ndarray instance with contiguous memory layout.

PyObject *UsmNDArray_MakeSimpleFromPtr(size_t nelems, int typenum, DPCTLSyclUSMRef ptr, DPCTLSyclQueueRef QRef, PyObject *owner)
Parameters:

  • nelems – Number of elements in one-dimensional array

  • typenum – Integer encoding type of array elements

  • ptr – Opaque pointer to USM allocation

  • QRef – Instance representing sycl::queue to be associated with output array

  • owner – Python object responsible for deallocation of USM memory

Returns:

One-dimensional usm_ndarray instance with contiguous memory layout.

PyObject *UsmNDArray_MakeFromPtr(int nd, const Py_ssize_t *shape, int typenum, const Py_ssize_t *strides, DPCTLSyclUSMRef ptr, DPCTLSyclQueueRef QRef, Py_ssize_t offset, PyObject *owner)
Parameters:

  • nd – Number of axis in output array

  • shape – Array of dimensional along each axis

  • typenum – Integer encoding type of array elements

  • stride – Array of strides for each axis

  • ptr – Opaque pointer to USM allocation

  • QRef – Instance representing sycl::queue to be associated with output array

  • offset – Offset to zero multi-index array element from the beginning of USM allocation

  • owner – Python object responsible for deallocation of USM memory

Returns:

Instance of usm_ndarray constructed from input parameters

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.