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* error_handler,
    int properties
    );

DPCTL_API __dpctl_give DPCTLSyclQueueRef
DPCTLQueue_CreateForDevice(
    __dpctl_keep const DPCTLSyclDeviceRef dRef,
    error_handler_callback* error_handler,
    int properties
    );

DPCTL_API void
DPCTLQueue_Delete(__dpctl_take DPCTLSyclQueueRef QRef);

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_IsInOrder(__dpctl_keep const DPCTLSyclQueueRef QRef);

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

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

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

DPCTL_API 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 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* 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.

Parameters:

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.

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* 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:

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.

Parameters:

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.

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 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_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 void
DPCTLQueue_MemAdvise(
    __dpctl_keep 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.

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.

DPCTL_API void
DPCTLQueue_Memcpy(
    __dpctl_keep const 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.

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.

DPCTL_API void
DPCTLQueue_Prefetch(
    __dpctl_keep 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.

Parameters:

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

DPCTL_API 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(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 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(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.