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

  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.

  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)

  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)

  Returns an `Event`.

  Changed in version 2011.2: Takes wait_for.