Queue class C wrapper¶

Overview¶

// global functions

DPCTL_API bool
DPCTLQueue_AreEq(
    __dpctl_keep const DPCTLSyclQueueRef QRef1,
    __dpctl_keep const DPCTLSyclQueueRef QRef2
    );

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_Copy(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_Create(
    __dpctl_keep const DPCTLSyclContextRef CRef,
    __dpctl_keep const DPCTLSyclDeviceRef DRef,
    error_handler_callback* handler,
    int properties
    );

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_CreateForDevice(
    __dpctl_keep const DPCTLSyclDeviceRef DRef,
    error_handler_callback* handler,
    int properties
    );

DPCTL_API void
DPCTLQueue_Delete(__dpctl_take DPCTLSyclQueueRef QRef);

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill128(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint64_t* Value,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill16(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint16_t Value,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill32(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint32_t Value,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill64(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint64_t Value,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill8(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint8_t Value,
    size_t Count
    );

DPCTL_API DPCTLSyclBackendType
DPCTLQueue_GetBackend(__dpctl_keep DPCTLSyclQueueRef QRef);

DPCTL_API __dpctl_give DPCTLSyclContextRef
DPCTLQueue_GetContext(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API __dpctl_give DPCTLSyclDeviceRef
DPCTLQueue_GetDevice(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API bool
DPCTLQueue_HasEnableProfiling(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API size_t
DPCTLQueue_Hash(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API bool
DPCTLQueue_IsInOrder(__dpctl_keep const DPCTLSyclQueueRef QRef);

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_MemAdvise(
    __dpctl_keep DPCTLSyclQueueRef QRef,
    const void* Ptr,
    size_t Count,
    int Advice
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Memcpy(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* Dest,
    const void* Src,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_MemcpyWithEvents(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* Dest,
    const void* Src,
    size_t Count,
    __dpctl_keep const DPCTLSyclEventRef* DepEvents,
    size_t DepEventsCount
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Memset(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint8_t Value,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Prefetch(
    __dpctl_keep DPCTLSyclQueueRef QRef,
    const void* Ptr,
    size_t Count
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_SubmitNDRange(
    __dpctl_keep const DPCTLSyclKernelRef KRef,
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    __dpctl_keep void** Args,
    __dpctl_keep const 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 DPCTLSyclEventRef* DepEvents,
    size_t NDepEvents
    );

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_SubmitRange(
    __dpctl_keep const DPCTLSyclKernelRef KRef,
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    __dpctl_keep void** Args,
    __dpctl_keep const DPCTLKernelArgType* ArgTypes,
    size_t NArgs,
    __dpctl_keep const size_t Range[3],
    size_t NRange,
    __dpctl_keep const DPCTLSyclEventRef* DepEvents,
    size_t NDepEvents
    );

DPCTL_API void
DPCTLQueue_Wait(__dpctl_keep const DPCTLSyclQueueRef QRef);

Detailed Documentation¶

Global Functions¶

DPCTL_API bool
DPCTLQueue_AreEq(
    __dpctl_keep const DPCTLSyclQueueRef QRef1,
    __dpctl_keep const DPCTLSyclQueueRef QRef2
    )

Checks if two DPCTLSyclQueueRef objects point to the same sycl::queue.

Parameters:

QRef1	First opaque pointer to the `sycl::queue`.
QRef2	Second opaque pointer to the `sycl::queue`.

Returns:

True if the underlying sycl::queue are same, false otherwise.

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_Copy(__dpctl_keep const DPCTLSyclQueueRef QRef)

Returns a copy of the DPCTLSyclQueueRef object.

Parameters:

QRef	DPCTLSyclQueueRef object to be copied.

Returns:

A new DPCTLSyclQueueRef created by copying the passed in DPCTLSyclQueueRef object.

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_Create(
    __dpctl_keep const DPCTLSyclContextRef CRef,
    __dpctl_keep const DPCTLSyclDeviceRef DRef,
    error_handler_callback* handler,
    int properties
    )

A wrapper for sycl::queue constructor to construct a new queue from the provided context, device, async handler and properties bit flags.

Parameters:

CRef	An opaque pointer to a sycl::context.
DRef	An opaque pointer to a sycl::device
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.

Returns:

An opaque DPCTLSyclQueueRef pointer containing the new sycl::queue object. A nullptr is returned if the queue could not be created.

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_CreateForDevice(
    __dpctl_keep const DPCTLSyclDeviceRef DRef,
    error_handler_callback* handler,
    int properties
    )

Constructs a sycl::queue object of the specified SYCL device.

Constructs a new SYCL queue for the specified SYCL device. The behavior of this function differs from the following queue constructor:

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 behaves the same way as the SYCL constructor.

Parameters:

DRef	An opaque pointer to a `sycl::device`.
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.

Returns:

An opaque DPCTLSyclQueueRef pointer containing the new sycl::queue object. A nullptr is returned if the queue could not be created.

DPCTL_API void
DPCTLQueue_Delete(__dpctl_take DPCTLSyclQueueRef QRef)

Delete the pointer after casting it to sycl::queue.

Parameters:

QRef	A DPCTLSyclQueueRef pointer that gets deleted.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill128(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint64_t* Value,
    size_t Count
    )

C-API wrapper for sycl::queue::fill.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A pointer to uint64_t array of 2 elements with value to fill.
Count	A number of 128-bit elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill16(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint16_t Value,
    size_t Count
    )

C-API wrapper for sycl::queue::fill.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A uint16_t value to fill.
Count	A number of uint16_t elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill32(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint32_t Value,
    size_t Count
    )

C-API wrapper for sycl::queue::fill.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A uint32_t value to fill.
Count	A number of uint32_t elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill64(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint64_t Value,
    size_t Count
    )

C-API wrapper for sycl::queue::fill.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A uint64_t value to fill.
Count	A number of uint64_t elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Fill8(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint8_t Value,
    size_t Count
    )

C-API wrapper for sycl::queue::fill.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A uint8_t value to fill.
Count	A number of uint8_t elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API DPCTLSyclBackendType
DPCTLQueue_GetBackend(__dpctl_keep DPCTLSyclQueueRef QRef)

Returns the Sycl backend for the provided sycl::queue.

Parameters:

QRef	An opaque pointer to the sycl queue.

Returns:

A enum DPCTLSyclBackendType corresponding to the backed for the queue.

DPCTL_API __dpctl_give DPCTLSyclContextRef
DPCTLQueue_GetContext(__dpctl_keep const DPCTLSyclQueueRef QRef)

Returns the Sycl context for the queue.

Parameters:

QRef	An opaque pointer to the sycl queue.

Returns:

A DPCTLSyclContextRef pointer to the sycl context for the queue.

DPCTL_API __dpctl_give DPCTLSyclDeviceRef
DPCTLQueue_GetDevice(__dpctl_keep const DPCTLSyclQueueRef QRef)

returns the Sycl device for the queue.

Parameters:

QRef	An opaque pointer to the sycl queue.

Returns:

A DPCTLSyclDeviceRef pointer to the sycl device for the queue.

DPCTL_API bool
DPCTLQueue_HasEnableProfiling(__dpctl_keep const DPCTLSyclQueueRef QRef)

C-API wrapper for sycl::queue::has_property<sycl::property::queue::enable_profiling>() that indicates whether the referenced queue was constructed with this property.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.

DPCTL_API size_t
DPCTLQueue_Hash(__dpctl_keep const DPCTLSyclQueueRef QRef)

C-API wrapper for std::hash<sycl::queue>’s operator().

Parameters:

QRef	An opaque pointer to the `sycl::queue`.

Returns:

Hash value of the underlying sycl::queue instance.

DPCTL_API bool
DPCTLQueue_IsInOrder(__dpctl_keep const DPCTLSyclQueueRef QRef)

C-API wrapper for sycl::queue::is_in_order that indicates whether the referenced queue is in-order or out-of-order.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_MemAdvise(
    __dpctl_keep DPCTLSyclQueueRef QRef,
    const void* Ptr,
    size_t Count,
    int Advice
    )

C-API wrapper for sycl::queue::mem_advise.

Parameters:

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.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::mem_advise function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Memcpy(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* Dest,
    const void* Src,
    size_t Count
    )

C-API wrapper for sycl::queue::memcpy.

Parameters:

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.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::memcpy function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_MemcpyWithEvents(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* Dest,
    const void* Src,
    size_t Count,
    __dpctl_keep const DPCTLSyclEventRef* DepEvents,
    size_t DepEventsCount
    )

C-API wrapper for sycl::queue::memcpy.

Parameters:

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.
DepEvents	A pointer to array of DPCTLSyclEventRef opaque pointers to dependent events.
DepEventsCount	A number of dependent events.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::memcpy function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Memset(
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    void* USMRef,
    uint8_t Value,
    size_t Count
    )

C-API wrapper for sycl::queue::memset.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
USMRef	An USM pointer to the memory to fill.
Value	A value to fill.
Count	A number of uint8_t elements to fill.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::fill function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_Prefetch(
    __dpctl_keep DPCTLSyclQueueRef QRef,
    const void* Ptr,
    size_t Count
    )

C-API wrapper for sycl::queue::prefetch.

Parameters:

QRef	An opaque pointer to the `sycl::queue`.
Ptr	An USM pointer to memory.
Count	A number of bytes to prefetch.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue::prefetch function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_SubmitNDRange(
    __dpctl_keep const DPCTLSyclKernelRef KRef,
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    __dpctl_keep void** Args,
    __dpctl_keep const 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 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<NRange>, *unwrap<kernel>(KRef)).

Todo sycl::buffer arguments are not supported yet.

Add support for id<Dims> WorkItemOffset

Parameters:

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.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue.submit() function.

DPCTL_API __dpctl_give DPCTLSyclEventRef
DPCTLQueue_SubmitRange(
    __dpctl_keep const DPCTLSyclKernelRef KRef,
    __dpctl_keep const DPCTLSyclQueueRef QRef,
    __dpctl_keep void** Args,
    __dpctl_keep const DPCTLKernelArgType* ArgTypes,
    size_t NArgs,
    __dpctl_keep const size_t Range[3],
    size_t NRange,
    __dpctl_keep const 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<NRange>, *unwrap<kernel>(KRef)).

Todo sycl::buffer arguments are not supported yet.

Add support for id<Dims> WorkItemOffset

Parameters:

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.

Returns:

An opaque pointer to the sycl::event returned by the sycl::queue.submit() function.

DPCTL_API void
DPCTLQueue_Wait(__dpctl_keep const DPCTLSyclQueueRef QRef)

Calls the sycl::queue::submit function to do a blocking wait on all enqueued tasks in the queue.

Parameters:

QRef	Opaque pointer to a `sycl::queue`.