dpctl.SyclQueue

class dpctl.SyclQueue(*args, **kwargs)

Python class representing sycl::queue. There are multiple ways to create a dpctl.SyclQueue object:

Invoking the constructor with no arguments creates a context using the default selector.
Example:
import dpctl

# Create a default SyclQueue
q = dpctl.SyclQueue()
print(q.sycl_device)
Invoking the constructor with specific filter selector string that creates a queue for the device corresponding to the filter string.
Example:
import dpctl

# Create in-order SyclQueue for either gpu, or cpu device
q = dpctl.SyclQueue("gpu,cpu", property="in_order")
print([q.sycl_device.is_gpu, q.sycl_device.is_cpu])
Invoking the constructor with a dpctl.SyclDevice object creates a queue for that device, automatically finding/creating a dpctl.SyclContext for the given device.
Example:
import dpctl

d = dpctl.SyclDevice("gpu")
q = dpctl.SyclQueue(d)
ctx = q.sycl_context
print(q.sycl_device == d)
print(any([ d == ctx_d for ctx_d in ctx.get_devices()]))
Invoking the constructor with a dpctl.SyclContext and a dpctl.SyclDevice creates a queue for given context and device.
Example:
import dpctl

# Create a CPU device using the opencl driver
cpu_d = dpctl.SyclDevice("opencl:cpu")
# Partition the CPU device into sub-devices with two cores each.
sub_devices = cpu_d.create_sub_devices(partition=2)
# Create a context common to all the sub-devices.
ctx = dpctl.SyclContext(sub_devices)
# create a queue for each sub-device using the common context
queues = [dpctl.SyclQueue(ctx, sub_d) for sub_d in sub_devices]
Invoking the constructor with a named PyCapsule with the name “SyclQueueRef” that carries a pointer to a sycl::queue object. The capsule will be renamed upon successful consumption to ensure one-time use. A new named capsule can be constructed by using dpctl.SyclQueue._get_capsule() method.

Parameters:

ctx (dpctl.SyclContext, optional) – Sycl context to create dpctl.SyclQueue from. If not specified, a single-device context will be created from the specified device.
dev (str, dpctl.SyclDevice, capsule, optional) –
Sycl device to create dpctl.SyclQueue from. If not specified, sycl device selected by sycl::default_selector is used. The argument must be explicitly specified if ctxt argument is provided.

If dev is a named PyCapsule called “SyclQueueRef” and ctxt is not specified, dpctl.SyclQueue instance is created from foreign sycl::queue object referenced by the capsule.
property (str, tuple(str), list(str), optional) – Defaults to None. The argument can be either “default”, “in_order”, “enable_profiling”, or a tuple containing these.

Raises:

SyclQueueCreationError – If the dpctl.SyclQueue object creation failed.
TypeError – In case of incorrect arguments given to constructors, unexpected types of input arguments, or in the case the input capsule contained a null pointer or could not be renamed.

Attributes:

`backend`	Returns the backend_type enum value for this queue.
`driver_version`	Returns the driver version for the device associated with this queue.
`has_enable_profiling`	True if SyclQueue was constructed with enabled_profiling property, False otherwise.
`is_in_order`	True if SyclQueue is in-order, False if it is out-of-order.
`name`	Returns the device name for the device associated with this queue.
`sycl_context`	Returns `SyclContext` underlying this queue
`sycl_device`	Returns `SyclDevice` underlying this queue

Public methods:

`addressof_ref`()	Returns the address of the C API DPCTLSyclQueueRef pointer as a `size_t`.
`get_sycl_context`()
`get_sycl_device`()
`mem_advise`(mem, count, advice)
`memcpy`(dest, src, count)	Copy memory from src to dst
`memcpy_async`(dest, src, count[, dEvents])	Copy memory from src to dst
`prefetch`(mem[, count])
`print_device_info`()	Print information about the SYCL device associated with this queue.
`submit`(kernel, args, gS[, lS, dEvents])
`submit_async`(kernel, args, gS[, lS, dEvents])
`submit_barrier`([dependent_events])	Submits a barrier to the queue.
`wait`()

Private methods:

`_get_capsule`()
`_submit_keep_args_alive`(args, events)	Keeps objects in args alive until tasks associated with events complete.

Attributes

SyclQueue.backend

Returns the backend_type enum value for this queue.

Returns:: The backend for the queue.
Return type:: backend_type

SyclQueue.driver_version

Returns the driver version for the device associated with this queue.

Returns:: The driver version of the device as a string.
Return type:: str

SyclQueue.has_enable_profiling: True if SyclQueue was constructed with enabled_profiling property, False otherwise.

SyclQueue.is_in_order: True if SyclQueue is in-order, False if it is out-of-order.

SyclQueue.name

Returns the device name for the device associated with this queue.

Returns:: The name of the device as a string.
Return type:: str

SyclQueue.sycl_context: Returns SyclContext underlying this queue

SyclQueue.sycl_device: Returns SyclDevice underlying this queue

Public methods

dpctl.SyclQueue.addressof_ref(self)

Returns the address of the C API DPCTLSyclQueueRef pointer as a size_t.

Returns:: The address of the DPCTLSyclQueueRef object used to create this dpctl.SyclQueue cast to a size_t.

dpctl.SyclQueue.get_sycl_context(self)

dpctl.SyclQueue.get_sycl_device(self)

dpctl.SyclQueue.mem_advise(self, mem, count, advice)

dpctl.SyclQueue.memcpy(self, dest, src, count): Copy memory from src to dst

dpctl.SyclQueue.memcpy_async(self, dest, src, count, dEvents=None): Copy memory from src to dst

dpctl.SyclQueue.prefetch(self, mem, count=0)

dpctl.SyclQueue.print_device_info(self): Print information about the SYCL device associated with this queue.

dpctl.SyclQueue.submit(self, kernel, args, gS, lS=None, dEvents=None)

dpctl.SyclQueue.submit_async(self, kernel, args, gS, lS=None, dEvents=None)

dpctl.SyclQueue.submit_barrier(self, dependent_events=None): Submits a barrier to the queue.

dpctl.SyclQueue.wait(self)

Private methods

dpctl.SyclQueue._get_capsule(self)

dpctl.SyclQueue._submit_keep_args_alive(args, events)

Keeps objects in args alive until tasks associated with events complete.

Parameters:

args (object) – Python object to keep alive. Typically a tuple with arguments to offloaded tasks
events (Tuple[dpctl.SyclEvent]) – Gating events The list or tuple of events associated with tasks working on Python objects collected in args.

Returns:

dpctl.SyclEvent: The event associated with the submission of host task.

Increments reference count of args and schedules asynchronous host_task to decrement the count once dependent events are complete.

N.B.: The host_task attempts to acquire Python GIL, and it is known to be unsafe during interpreter shudown sequence. It is thus strongly advised to ensure that all submitted host_task complete before the end of the Python script.