.. index:: pair: group; Queue class C wrapper .. _doxid-d9/db1/group__QueueInterface: Queue class C wrapper ===================== .. toctree:: :hidden: Overview ~~~~~~~~ .. ref-code-block:: cpp :class: doxyrest-overview-code-block // global functions DPCTL_API bool :ref:`DPCTLQueue_AreEq`( __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef1, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef2 ); DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` :ref:`DPCTLQueue_Copy`(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` :ref:`DPCTLQueue_Create`( __dpctl_keep const :ref:`DPCTLSyclContextRef` CRef, __dpctl_keep const :ref:`DPCTLSyclDeviceRef` DRef, :ref:`error_handler_callback`* error_handler, int properties ); DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` :ref:`DPCTLQueue_CreateForDevice`( __dpctl_keep const :ref:`DPCTLSyclDeviceRef` dRef, :ref:`error_handler_callback`* error_handler, int properties ); DPCTL_API void :ref:`DPCTLQueue_Delete`(__dpctl_take :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API :ref:`DPCTLSyclBackendType` :ref:`DPCTLQueue_GetBackend`(__dpctl_keep :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API __dpctl_give :ref:`DPCTLSyclContextRef` :ref:`DPCTLQueue_GetContext`(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API __dpctl_give :ref:`DPCTLSyclDeviceRef` :ref:`DPCTLQueue_GetDevice`(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API bool :ref:`DPCTLQueue_IsInOrder`(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef); DPCTL_API void :ref:`DPCTLQueue_MemAdvise`( __dpctl_keep :ref:`DPCTLSyclQueueRef` QRef, const void* Ptr, size_t Count, int Advice ); DPCTL_API void :ref:`DPCTLQueue_Memcpy`( __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, void* Dest, const void* Src, size_t Count ); DPCTL_API void :ref:`DPCTLQueue_Prefetch`( __dpctl_keep :ref:`DPCTLSyclQueueRef` QRef, const void* Ptr, size_t Count ); DPCTL_API :ref:`DPCTLSyclEventRef` :ref:`DPCTLQueue_SubmitNDRange`( __dpctl_keep const :ref:`DPCTLSyclKernelRef` KRef, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, __dpctl_keep void** Args, __dpctl_keep const :ref:`DPCTLKernelArgType`* ArgTypes, size_t NArgs, __dpctl_keep const size_t gRange[3], __dpctl_keep const size_t lRange[3], size_t NDims, __dpctl_keep const :ref:`DPCTLSyclEventRef`* DepEvents, size_t NDepEvents ); DPCTL_API :ref:`DPCTLSyclEventRef` :ref:`DPCTLQueue_SubmitRange`( __dpctl_keep const :ref:`DPCTLSyclKernelRef` KRef, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, __dpctl_keep void** Args, __dpctl_keep const :ref:`DPCTLKernelArgType`* ArgTypes, size_t NArgs, __dpctl_keep const size_t Range[3], size_t NRange, __dpctl_keep const :ref:`DPCTLSyclEventRef`* DepEvents, size_t NDepEvents ); DPCTL_API void :ref:`DPCTLQueue_Wait`(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef); .. _details-d9/db1/group__QueueInterface: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ Global Functions ---------------- .. index:: pair: function; DPCTLQueue_AreEq .. _doxid-d9/db1/group__QueueInterface_1ga8a957bd257ec77b0f57bcb3c35e1e479: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API bool DPCTLQueue_AreEq( __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef1, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef2 ) Checks if two DPCTLSyclQueueRef objects point to the same sycl::queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef1 - First opaque pointer to the sycl queue. * - QRef2 - Second opaque pointer to the sycl queue. .. rubric:: Returns: True if the underlying sycl::queue are same, false otherwise. .. index:: pair: function; DPCTLQueue_Copy .. _doxid-d9/db1/group__QueueInterface_1gad8d2312b954460ad658b2f1080c0dee3: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` DPCTLQueue_Copy(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef) Returns a copy of the DPCTLSyclQueueRef object. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - DPCTLSyclQueueRef object to be copied. .. rubric:: Returns: A new DPCTLSyclQueueRef created by copying the passed in DPCTLSyclQueueRef object. .. index:: pair: function; DPCTLQueue_Create .. _doxid-d9/db1/group__QueueInterface_1ga27d56aeb34230271b80ee158b4c22e7f: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` DPCTLQueue_Create( __dpctl_keep const :ref:`DPCTLSyclContextRef` CRef, __dpctl_keep const :ref:`DPCTLSyclDeviceRef` DRef, :ref:`error_handler_callback`* error_handler, int properties ) A wrapper for sycl::queue contructor to construct a new queue from the provided context, device, async handler and propertis bit flags. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - CRef - An opaque pointer to a sycl::context. * - DRef - An opaque pointer to a sycl::device * - error_handler - A callback function that will be invoked by the async_handler used during queue creation. Can be NULL if no async_handler is needed. * - properties - A combination of bit flags using the values defined in the DPCTLQueuePropertyType enum. The bit flags are used to create a sycl::property_list that is passed to the SYCL queue constructor. .. rubric:: Returns: An opaque DPCTLSyclQueueRef pointer containing the new sycl::queue object. A nullptr is returned if the queue could not be created. .. index:: pair: function; DPCTLQueue_CreateForDevice .. _doxid-d9/db1/group__QueueInterface_1gaefe0a82877a107fc17b3826047fa833d: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API __dpctl_give :ref:`DPCTLSyclQueueRef` DPCTLQueue_CreateForDevice( __dpctl_keep const :ref:`DPCTLSyclDeviceRef` dRef, :ref:`error_handler_callback`* error_handler, int properties ) Constructs a ``sycl::queue`` object of the specified SYCL device. Constructs a new SYCL queue for the specified SYCL device. The behaviour of this function differs from the following queue constructor: .. ref-code-block:: cpp queue( const device &syclDevice, const async_handler &asyncHandler, const property_list &propList = {} ) Unlike the SYCL queue constructor, we try not to create a new SYCL context for the device and instead look to reuse a previously cached SYCL context for the device (refer dpctl_sycl_device_manager.cpp). DPCTL caches contexts only for root devices and for all custom devices the function begaves the same way as the SYCL constructor. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - dRef - An opaque pointer to a ``sycl::device``. * - error_handler - A callback function that will be invoked by the async_handler used during queue creation. Can be NULL if no async_handler is needed. * - properties - A combination of bit flags using the values defined in the DPCTLQueuePropertyType enum. The bit flags are used to create a ``sycl::property_list`` that is passed to the SYCL queue constructor. .. rubric:: Returns: An opaque DPCTLSyclQueueRef pointer containing the new ``sycl::queue`` object. A nullptr is returned if the queue could not be created. .. index:: pair: function; DPCTLQueue_Delete .. _doxid-d9/db1/group__QueueInterface_1ga44557847663338a67f423a06ecf9192a: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API void DPCTLQueue_Delete(__dpctl_take :ref:`DPCTLSyclQueueRef` QRef) Delete the pointer after casting it to sycl::queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - A DPCTLSyclQueueRef pointer that gets deleted. .. index:: pair: function; DPCTLQueue_GetBackend .. _doxid-d9/db1/group__QueueInterface_1ga8c3629a8627e9748cdec34688f6ce908: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API :ref:`DPCTLSyclBackendType` DPCTLQueue_GetBackend(__dpctl_keep :ref:`DPCTLSyclQueueRef` QRef) Returns the Sycl backend for the provided sycl::queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. .. rubric:: Returns: A enum DPCTLSyclBackendType corresponding to the backed for the queue. .. index:: pair: function; DPCTLQueue_GetContext .. _doxid-d9/db1/group__QueueInterface_1gad11e27086f2cee7f3d22f33de1a24bc9: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API __dpctl_give :ref:`DPCTLSyclContextRef` DPCTLQueue_GetContext(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef) Returns the Sycl context for the queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. .. rubric:: Returns: A DPCTLSyclContextRef pointer to the sycl context for the queue. .. index:: pair: function; DPCTLQueue_GetDevice .. _doxid-d9/db1/group__QueueInterface_1ga44095b28dfb5c357e6c065749e9aa8c0: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API __dpctl_give :ref:`DPCTLSyclDeviceRef` DPCTLQueue_GetDevice(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef) returns the Sycl device for the queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. .. rubric:: Returns: A DPCTLSyclDeviceRef pointer to the sycl device for the queue. .. index:: pair: function; DPCTLQueue_IsInOrder .. _doxid-d9/db1/group__QueueInterface_1ga0738e262108a1ac8f43f227548724f07: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API bool DPCTLQueue_IsInOrder(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef) C-API wrapper for sycl::queue::is_in_order that indicates whether the referenced queue is in-order or out-of-order. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. .. index:: pair: function; DPCTLQueue_MemAdvise .. _doxid-d9/db1/group__QueueInterface_1ga0ef8f0c4ee3fd1e0289633ffe3d283dc: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API void DPCTLQueue_MemAdvise( __dpctl_keep :ref:`DPCTLSyclQueueRef` QRef, const void* Ptr, size_t Count, int Advice ) C-API wrapper for sycl::queue::mem_advise, the function waits on an event till the operation completes. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. * - Ptr - An USM pointer to memory. * - Count - A number of bytes to prefetch. * - Advice - Device-defined advice for the specified allocation. A value of 0 reverts the advice for Ptr to the default behavior. .. index:: pair: function; DPCTLQueue_Memcpy .. _doxid-d9/db1/group__QueueInterface_1ga25103f4d9872482ce6efde712a807979: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API void DPCTLQueue_Memcpy( __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, void* Dest, const void* Src, size_t Count ) C-API wrapper for sycl::queue::memcpy, the function waits on an event till the memcpy operation completes. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. * - Dest - An USM pointer to the destination memory. * - Src - An USM pointer to the source memory. * - Count - A number of bytes to copy. .. index:: pair: function; DPCTLQueue_Prefetch .. _doxid-d9/db1/group__QueueInterface_1ga4281ab0ca2559019d062411477f85a01: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API void DPCTLQueue_Prefetch( __dpctl_keep :ref:`DPCTLSyclQueueRef` QRef, const void* Ptr, size_t Count ) C-API wrapper for sycl::queue::prefetch, the function waits on an event till the prefetch operation completes. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - An opaque pointer to the sycl queue. * - Ptr - An USM pointer to memory. * - Count - A number of bytes to prefetch. .. index:: pair: function; DPCTLQueue_SubmitNDRange .. _doxid-d9/db1/group__QueueInterface_1gaac9356153363bb89ade3116816fca94b: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API :ref:`DPCTLSyclEventRef` DPCTLQueue_SubmitNDRange( __dpctl_keep const :ref:`DPCTLSyclKernelRef` KRef, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, __dpctl_keep void** Args, __dpctl_keep const :ref:`DPCTLKernelArgType`* ArgTypes, size_t NArgs, __dpctl_keep const size_t gRange[3], __dpctl_keep const size_t lRange[3], size_t NDims, __dpctl_keep const :ref:`DPCTLSyclEventRef`* DepEvents, size_t NDepEvents ) Submits the kernel to the specified queue with the provided nd_range argument. A wrapper over sycl::queue.submit(). The function takes an interoperability kernel, the kernel arguments, and a Sycl queue as input. The kernel is submitted as parallel_for(nd_range, \*unwrap(KRef)). Todo sycl::buffer arguments are not supported yet. Add support for id WorkItemOffset .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - KRef - Opaque pointer to an OpenCL interoperability kernel wrapped inside a sycl::kernel. * - QRef - Opaque pointer to the sycl::queue where the kernel will be enqueued. * - Args - An array of void\* pointers that represent the kernel arguments for the kernel. * - ArgTypes - An array of DPCTLKernelArgType enum values that represent the type of each kernel argument. * - NArgs - Size of Args. * - gRange - Defines the overall dimension of the dispatch for the kernel. The array can have up to three dimensions. * - lRange - Defines the iteration domain of a single work-group in a parallel dispatch. The array can have up to three dimensions. * - NDims - The number of dimensions for both local and global ranges. * - DepEvents - List of dependent DPCTLSyclEventRef objects (events) for the kernel. We call sycl::handler.depends_on for each of the provided events. * - NDepEvents - Size of the DepEvents list. .. rubric:: Returns: An opaque pointer to the sycl::event returned by the sycl::queue.submit() function. .. index:: pair: function; DPCTLQueue_SubmitRange .. _doxid-d9/db1/group__QueueInterface_1ga9ed0d59f789b4fb0959b0af022fdbe23: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API :ref:`DPCTLSyclEventRef` DPCTLQueue_SubmitRange( __dpctl_keep const :ref:`DPCTLSyclKernelRef` KRef, __dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef, __dpctl_keep void** Args, __dpctl_keep const :ref:`DPCTLKernelArgType`* ArgTypes, size_t NArgs, __dpctl_keep const size_t Range[3], size_t NRange, __dpctl_keep const :ref:`DPCTLSyclEventRef`* DepEvents, size_t NDepEvents ) Submits the kernel to the specified queue with the provided range argument. A wrapper over sycl::queue.submit(). The function takes an interoperability kernel, the kernel arguments, and a Sycl queue as input. The kernel is submitted as parallel_for(range, \*unwrap(KRef)). Todo sycl::buffer arguments are not supported yet. Add support for id WorkItemOffset .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - KRef - Opaque pointer to an OpenCL interoperability kernel wrapped inside a sycl::kernel. * - QRef - Opaque pointer to the sycl::queue where the kernel will be enqueued. * - Args - An array of void\* pointers that represent the kernel arguments for the kernel. * - ArgTypes - An array of DPCTLKernelArgType enum values that represent the type of each kernel argument. * - NArgs - Size of Args and ArgTypes. * - Range - Defines the overall dimension of the dispatch for the kernel. The array can have up to three dimensions. * - NRange - Size of the gRange array. * - DepEvents - List of dependent DPCTLSyclEventRef objects (events) for the kernel. We call sycl::handler.depends_on for each of the provided events. * - NDepEvents - Size of the DepEvents list. .. rubric:: Returns: An opaque pointer to the sycl::event returned by the sycl::queue.submit() function. .. index:: pair: function; DPCTLQueue_Wait .. _doxid-d9/db1/group__QueueInterface_1ga3411357b2a09bad80be5b4fee8a8ed44: .. ref-code-block:: cpp :class: doxyrest-title-code-block DPCTL_API void DPCTLQueue_Wait(__dpctl_keep const :ref:`DPCTLSyclQueueRef` QRef) Calls the sycl::queue.submit function to do a blocking wait on all enqueued tasks in the queue. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - QRef - Opaque pointer to a sycl::queue.