dpctl.SyclContext¶

class dpctl.SyclContext¶

Python class representing cl::sycl::context. There are multiple ways to create a dpctl.SyclContext object:

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

# Create a default SyclContext
ctx = dpctl.SyclContext()
print(ctx.get_devices())
Invoking the constuctor with a specific filter string that creates a context for the device corresponding to the filter string.
Example
import dpctl

# Create SyclContext for a gpu device
ctx = dpctl.SyclContext("gpu")
d = ctx.get_devices()[0]
assert(d.is_gpu)
Invoking the constuctor with a dpctl.SyclDevice object creates a context for that device.
Example
import dpctl

# Create a level zero gpu device
d = dpctl.SyclDevice("level_zero:gpu")
ctx = dpctl.SyclContext(d)
d = ctx.get_devices()[0]
assert(d.is_gpu)
Invoking the constuctor with a list of dpctl.SyclDevice objects creates a common context for all the devices. This constructor call is especially useful when creation a context for multiple sub-devices.
Example
import dpctl

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

Parameters

arg (optional) – Defaults to None. The argument can be a selector string, a dpctl.SyclDevice instance, a list of dpctl.SyclDevice objects, or a named PyCapsule called “SyclContextRef”.

Raises

MemoryError – If the constructor could not allocate necessary temporary memory.
ValueError – If the dpctl.SyclContext object creation failed.
TypeError – If the list of dpctl.SyclDevice objects was empty, or the input capsule contained a null pointer or could not be renamed.

Attributes:

device_count

The number of sycl devices associated with the dpctl.SyclContext instance.

Private methods:

_get_capsule

Returns a copy of the underlying sycl::context pointer as a void pointer inside a named PyCapsule that has the name SyclContextRef.

Public methods:

`addressof_ref`	Returns the address of the `DPCTLSyclContextRef` pointer as a `size_t`.
`get_devices`	Returns the list of `dpctl.SyclDevice` objects associated with `dpctl.SyclContext` instance.

Detail¶

Private methods¶

SyclContext._get_capsule()

Returns a copy of the underlying sycl::context pointer as a void pointer inside a named PyCapsule that has the name SyclContextRef. The ownership of the pointer inside the capsule is passed to the caller, and pointer is deleted when the capsule goes out of scope.

Returns

A capsule object storing a copy of the sycl::context pointer belonging to thus dpctl.SyclContext instance.

Return type

pycapsule

Raises

ValueError – If the DPCTLContext_Copy fails to copy the sycl::context pointer.

Public methods¶

SyclContext.addressof_ref()

Returns the address of the DPCTLSyclContextRef pointer as a size_t.

Returns

The address of the DPCTLSyclContextRef object used to create this dpctl.SyclContext cast to a size_t.

Return type

int

SyclContext.device_count

The number of sycl devices associated with the dpctl.SyclContext instance.

Returns

Number of devices associated with the context.

Return type

int

Raises

ValueError – If DPCTLContext_DeviceCount led to a failure.

SyclContext.get_devices()

Returns the list of dpctl.SyclDevice objects associated with dpctl.SyclContext instance.

Returns

A list of dpctl.SyclDevice objects that belong to this context.

Return type

list

Raises

ValueError – If the DPCTLContext_GetDevices call returned NULL instead of a DPCTLDeviceVectorRef object.