dpctl.SyclContext

class dpctl.SyclContext(arg=None)

A Python wrapper for the sycl::context C++ class.

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 constructor 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 constructor 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 constructor 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 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)
assert(len(ctx.get_devices) == len(sub_devices))

• Invoking the constructor 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.

• SyclContextCreationError – 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.

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.

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.

Attributes

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.

Public methods

dpctl.SyclContext.addressof_ref(self)

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

dpctl.SyclContext.get_devices(self)

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.

Private methods

dpctl.SyclContext._get_capsule(self)

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.