OpenCL Runtime: Command Queues and Events

Command Queue

class pyopencl.CommandQueue(context, device=None, properties=None)

Create a new command queue. properties is a bit field consisting of command_queue_properties values.

If device is None, one of the devices in context is chosen in an implementation-defined manner.

properties may be a bitwise combination of values from queue_properties (or None which is equivalent to passing 0). This is compatible with both OpenCL 1.x and 2.x.

For OpenCL 2.0 and above, properties may also be a sequence of keys and values from queue_properties as accepted by clCreateCommandQueueWithProperties() (see the OpenCL spec for details). The trailing 0 is added automatically and does not need to be included.

A CommandQueue may be used as a context manager, like this:

with cl.CommandQueue(self.cl_context) as queue:
    enqueue_stuff(queue, ...)

finish() is automatically called at the end of the with-delimited context, and further operations on the queue are considered an error.

Added in version 2013.1: Context manager capability.

Changed in version 2018.2: Added the sequence-of-properties interface for OpenCL 2.

Changed in version 2022.1.4: Use of a command queue after its context manager completes is now considered an error. pyopencl will warn about this for a transitionary period and will start raising an exception in 2023.

info

Lower case versions of the command_queue_info constants may be used as attributes on instances of this class to directly query info attributes.

get_info(param)

See command_queue_info for values of param.

set_property(prop, enable)

See command_queue_properties for possible values of prop. enable is a bool.

Unavailable in OpenCL 1.1 and newer.

flush()

finish()

static from_int_ptr(int_ptr_value: int, retain: bool = True) → pyopencl._cl.CommandQueue

(static method) Return a new Python object referencing the C-level cl_command_queue object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr

Return an integer corresponding to the pointer value of the underlying cl_command_queue. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

Event

class pyopencl.Event

info

Lower case versions of the event_info constants may be used as attributes on instances of this class to directly query info attributes.

profile

An instance of ProfilingInfoGetter.

get_info(param)

See event_info for values of param.

get_profiling_info(param)

See profiling_info for values of param. See profile for an easier way of obtaining the same information.

wait()

static from_int_ptr(int_ptr_value: int, retain: bool = True) → pyopencl._cl.Event

(static method) Return a new Python object referencing the C-level cl_event object at the location pointed to by int_ptr_value. The relevant clRetain* function will be called if retain is True.If the previous owner of the object will not release the reference, retain should be set to False, to effectively transfer ownership to pyopencl.

Added in version 2013.2.

Changed in version 2016.1: retain added.

int_ptr

Return an integer corresponding to the pointer value of the underlying cl_event. Use from_int_ptr() to turn back into a Python object.

Added in version 2013.2.

set_callback(type, cb)

Add the callback cb with signature cb(status) to the callback queue for the event status type (one of the values of command_execution_status, except command_execution_status.QUEUED).

See the OpenCL specification for restrictions on what cb may and may not do.

Added in version 2015.2.

Instances of this class are hashable, and two instances of this class may be compared using “==” and “!=”. (Hashability was added in version 2011.2.) Two objects are considered the same if the underlying OpenCL object is the same, as established by C pointer equality.

class pyopencl.ProfilingInfoGetter

info

Lower case versions of the profiling_info constants may be used as attributes on the attribute profile of this class to directly query profiling info.

For example, you may use evt.profile.end instead of evt.get_profiling_info(pyopencl.profiling_info.END).

Event Subclasses

class pyopencl.UserEvent(context)

A subclass of Event. Only available with OpenCL 1.1 and newer.

Added in version 0.92.

set_status(status)

See command_execution_status for possible values of status.

class pyopencl.NannyEvent

Transfers between host and device return events of this type. They hold a reference to the host-side buffer and wait for the transfer to complete when they are freed. Therefore, they can safely release the reference to the object they’re guarding upon destruction.

A subclass of Event.

Added in version 2011.2.

get_ward()

wait()

In addition to performing the same wait as Event.wait(), this method also releases the reference to the guarded object.

Synchronization Functions

pyopencl.wait_for_events(events)

pyopencl.enqueue_barrier(queue, wait_for=None)

Enqueues a barrier operation. which ensures that all queued commands in command_queue have finished execution. This command is a synchronization point.

Added in version 0.91.5.

Changed in version 2011.2: Takes wait_for and returns an Event

pyopencl.enqueue_marker(queue, wait_for=None)

Returns an Event.

Changed in version 2011.2: Takes wait_for.