.. _dpctl_capi: :py:mod:`dpctl` C API ===================== :py:mod:`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 ----------------- .. c:struct:: PySyclDeviceObject .. c:struct:: PySyclDeviceType .. c:struct:: PySyclContextObject .. c:struct:: PySyclContextType .. c:struct:: PySyclQueueObject .. c:struct:: PySyclQueueType .. c:struct:: PySyclEventObject .. c:struct:: PySyclEventType .. c:struct:: Py_MemoryObject .. c:struct:: Py_MemoryType .. c:struct:: PyUSMArrayObject .. c:struct:: PyUSMArrayType .. c:struct:: PySyclKernelObject .. c:struct:: PySyclKernelType .. c:struct:: PySyclProgramObject .. c:struct:: PySyclProgramType To check whether a particular Python object is an instance of :py:class:`dpctl.SyclQueue`: .. code-block:: C :caption: Check if an object is of type :c:struct:`PySyclQueueType` #include "Python.h" #include "dpctl_capi.h" int PySyclQueue_Check(PyObject *o) { return PyObject_TypeCheck(o, &PySyclQueueType); } API for :c:struct:`PySyclDeviceObject` -------------------------------------- .. c:function:: DPCTLSyclDeviceRef SyclDevice_GetDeviceRef(struct PySyclDeviceObject *o) :param o: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclDeviceRef` .. c:function:: struct PySyclDeviceObject * SyclDevice_Make(DPCTLSyclDeviceRef DRef) :param DRef: instance of :c:struct:`DPCTLSyclDeviceRef` :returns: new Python object of type :c:struct:`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 :c:struct:`PySyclContextObject` --------------------------------------- .. c:function:: DPCTLSyclContextRef SyclContext_GetContextRef(struct PySyclContextObject *o) :param o: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclContextRef` .. c:function:: struct PySyclContextObject * SyclContext_Make(DPCTLSyclContextRef CRef) :param CRef: instance of :c:struct:`DPCTLSyclContextRef` :returns: new Python object of type :c:struct:`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 :c:struct:`PySyclQueueObject` ------------------------------------- .. c:function:: DPCTLSyclQueueRef SyclQueue_GetQueueRef(struct PySyclQueueObject *o) :param o: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclQueueRef` .. c:function:: struct PySyclQueueObject * SyclQueue_Make(DPCTLSyclQueueRef QRef) :param QRef: instance of :c:struct:`DPCTLSyclQueueRef` :returns: new Python object of type :c:struct:`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 :c:struct:`PySyclEventObject` ------------------------------------- .. c:function:: DPCTLSyclEventRef SyclEvent_GetEventRef(struct PySyclEventObject *o) :param o: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclEventRef` .. c:function:: struct PySyclEventObject * SyclEvent_Make(DPCTLSyclEventRef ERef) :param ERef: instance of :c:struct:`DPCTLSyclEventRef` :returns: new Python object of type :c:struct:`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 :c:struct:`Py_MemoryObject` ----------------------------------- .. c:function:: DPCTLSyclUSMRef Memory_GetUsmPointer(struct Py_MemoryObject *o) :param o: Input object :returns: Opaque pointer to USM allocation represented by Python object. .. c:function:: DPCTLSyclContextRef Memory_GetSyclContext(struct Py_MemoryObject *o) :param o: Input object :returns: Returns borrowed instance of :c:struct:`PySyclContextRef` corresponding to ``sycl::context`` to which USM allocation represented by input Python object is bound. .. c:function:: DPCTLSyclQueueRef Memory_GetSyclQueue(struct Py_MemoryObject *o) :param o: Input object :returns: Returns borrowed instance of :c:struct:`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. .. c:function:: size_t Memory_GetNumBytes(struct Py_MemoryObject *o) :param o: Input object :returns: Size of USM allocation in bytes. .. c:function:: struct Py_MemoryObject * Memory_Make(DPCTLSyclUSMRef ptr, size_t nbytes, DPCTLSyclQueueRef QRef, PyObject *owner) :param ptr: Opaque pointer in unified address space :param nbytes: The size of allocation in bytes :param QRef: instance of :c:struct:`PySyclQueueRef` corresponding to ``sycl::queue`` to be associated with this allocation :param 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. .. c:function:: void * Memory_GetOpaquePointer(struct Py_MemoryObject *o) :param o: Input object :returns: Returns opaque pointer to `std::shared_ptr` which manages the USM allocation, or a `nullptr` if the USM allocation represented by `o` is not managed by the smart pointer. API for :c:struct:`PyUSMArrayObject` ------------------------------------ .. c:function:: char * UsmNDArray_GetData(struct PyUSMArrayObject *arr) :param arr: Input object :returns: Pointer to array element referred to by all-zeros multi-index. .. c:function:: int UsmNDArray_GetNDim(struct PyUSMArrayObject *arr) :param 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. .. c:function:: Py_ssize_t * UsmNDArray_GetShape(struct PyUSMArrayObject *arr) :param 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 :c:func:`UsmNDArray_GetNDim` applied to input object ``arr``. .. c:function:: Py_ssize_t * UsmNDArray_GetStrides(struct PyUSMArrayObject *arr) :param 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 :c:func:`UsmNDArray_GetNDim` applied to input object ``arr``. .. c:function:: int UsmNDarray_GetTypenum(struct PyUSMArrayObject *arr) :param 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 :py:mod:`numpy`. See `NumPy Dtype C-API `_. .. c:function:: int UsmNDarray_GetElementSize(struct PyUSMArrayObject *arr) :param arr: Input object :returns: Size of single element of the array in bytes. .. c:function:: int UsmNDarray_GetFlags(struct PyUSMArrayObject *arr) :param 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. .. c:function:: DPCTLSyclQueueRef UsmNDarray_GetQueueRef(struct PyUSMArrayObject *arr) :param arr: Input object :returns: A borrowed instance of :c:struct:`DPCTLSyclQueueRef` The returned value corresponds to ``sycl::queue`` associated with underlying USM allocation. .. c:function:: Py_ssize_t UsmNDArray_GetOffset(struct PyUSMArrayObject *arr) :param arr: Input object :returns: Offset of zero multi-index array element from the beginning of the USM allocation. .. c:function:: PyObject * UsmNDArray_GetUSMData(struct PyUSMArrayObject *arr) :param arr: Input object :returns: Python memory object underlying input array `arr`. .. c:function:: void UsmNDArray_SetWritableFlag(struct PyUSMArrayObject *arr, int flag) :param arr: Input object :param 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. .. c:function:: PyObject * UsmNDArray_MakeSimpleFromMemory(int nd, const Py_ssize_t *shape, int typenum, struct Py_MemoryObject *mobj, Py_ssize_t offset, char order) :param nd: Dimensionality of array :param shape: Array with array sizes for each dimension :param typenum: Integer encoding type of array elements :param mobj: Python USM memory object :param offset: Offset to zero multi-index array element from the beginning of USM allocation :param order: Memory layout of the array ('C' for C-contiguous or row-major layout, 'F' for F-contiguous or column-major layout) :returns: :py:class:`usm_ndarray` instance with contiguous memory layout. .. c:function:: PyObject * UsmNDArray_MakeSimpleFromPtr(size_t nelems, int typenum, DPCTLSyclUSMRef ptr, DPCTLSyclQueueRef QRef, PyObject *owner) :param nelems: Number of elements in one-dimensional array :param typenum: Integer encoding type of array elements :param ptr: Opaque pointer to USM allocation :param QRef: Instance representing ``sycl::queue`` to be associated with output array :param owner: Python object responsible for deallocation of USM memory :return: One-dimensional :py:class:`usm_ndarray` instance with contiguous memory layout. .. c:function:: 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) :param nd: Number of axis in output array :param shape: Array of dimensional along each axis :param typenum: Integer encoding type of array elements :param stride: Array of strides for each axis :param ptr: Opaque pointer to USM allocation :param QRef: Instance representing ``sycl::queue`` to be associated with output array :param offset: Offset to zero multi-index array element from the beginning of USM allocation :param owner: Python object responsible for deallocation of USM memory :returns: Instance of :py:class:`usm_ndarray` constructed from input parameters API for :c:struct:`PySyclKernelObject` -------------------------------------- .. c:function:: DPCTLSyclKernelRef SyclKernel_GetKernelRef(struct PySyclKernelObject *krn) :param krn: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclKernelRef` corresponding to ``sycl::kernel`` .. c:function:: struct PySyclKernelObject * SyclKernel_Make(DPCTLSyclKernelRef KRef) :param KRef: instance of :c:struct:`DPCTLSyclKernelRef` :returns: new Python object of type :c:struct:`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 :c:struct:`PySyclProgramObject` --------------------------------------- .. c:function:: DPCTLSyclKernelBundleRef SyclProgram_GetKernelBundleRef(struct PySyclProgramObject *prog) :param prog: Input object :returns: borrowed instance of :c:struct:`DPCTLSyclKernelBundleRef` corresponding to ``sycl::kernel_bundle`` .. c:function:: struct PySyclProgramObject * SyclProgram_Make(DPCTLSyclKernelBundleRef KBRef) :param KBRef: instance of :c:struct:`DPCTLSyclKernelBundleRef` :returns: new Python object of type :c:struct:`PySyclProgramType` Note that function does not change the ownership of the ``KBRef`` instance and the caller remains responsible for freeing ``KBRef`` as appropriate.