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.

New 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.

New 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.

New 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.

New 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.

New 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.

New in version 2015.2.

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.

New 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.

New 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)[source]#: Enqueues a barrier operation. which ensures that all queued commands in command_queue have finished execution. This command is a synchronization point.

New in version 0.91.5.

Changed in version 2011.2: Takes wait_for and returns an Event

pyopencl.enqueue_marker(queue, wait_for=None)[source]#: Returns an Event.

Changed in version 2011.2: Takes wait_for.