Class command

Class command_queue

boost::compute::command_queue — A command queue.

Synopsis

// In header: <boost/compute/command_queue.hpp>


class command_queue {
public:

  enum properties { enable_profiling = = CL_QUEUE_PROFILING_ENABLE, 
                    enable_out_of_order_execution = = CL_QUEUE_OUT_OF_ORDER_EXEC_MODE_ENABLE };

  enum map_flags { map_read = = CL_MAP_READ, map_write = = CL_MAP_WRITE };
  // construct/copy/destruct
  command_queue();
  explicit command_queue(cl_command_queue, bool = true);
  command_queue(const context &, const device &, 
                cl_command_queue_properties = 0);
  command_queue(const command_queue &);
  command_queue(command_queue &&) noexcept;
  command_queue & operator=(const command_queue &);
  command_queue & operator=(command_queue &&) noexcept;
  ~command_queue();

  // public member functions
  cl_command_queue & get() const;
  device get_device() const;
  context get_context() const;
  template<typename T> T get_info(cl_command_queue_info) const;
  template<int Enum> unspecified get_info() const;
  cl_command_queue_properties get_properties() const;
  void enqueue_read_buffer(const buffer &, size_t, size_t, void *, 
                           const wait_list & = wait_list());
  event enqueue_read_buffer_async(const buffer &, size_t, size_t, void *, 
                                  const wait_list & = wait_list());
  void enqueue_read_buffer_rect(const buffer &, const size_t, const size_t, 
                                const size_t, size_t, size_t, size_t, size_t, 
                                void *, const wait_list & = wait_list());
  void enqueue_write_buffer(const buffer &, size_t, size_t, const void *, 
                            const wait_list & = wait_list());
  event enqueue_write_buffer_async(const buffer &, size_t, size_t, 
                                   const void *, 
                                   const wait_list & = wait_list());
  void enqueue_write_buffer_rect(const buffer &, const size_t, const size_t, 
                                 const size_t, size_t, size_t, size_t, 
                                 size_t, void *, 
                                 const wait_list & = wait_list());
  event enqueue_copy_buffer(const buffer &, const buffer &, size_t, size_t, 
                            size_t, const wait_list & = wait_list());
  event enqueue_copy_buffer_rect(const buffer &, const buffer &, const size_t, 
                                 const size_t, const size_t, size_t, size_t, 
                                 size_t, size_t, 
                                 const wait_list & = wait_list());
  event enqueue_fill_buffer(const buffer &, const void *, size_t, size_t, 
                            size_t, const wait_list & = wait_list());
  void * enqueue_map_buffer(const buffer &, cl_map_flags, size_t, size_t, 
                            const wait_list & = wait_list());
  event enqueue_unmap_buffer(const buffer &, void *, 
                             const wait_list & = wait_list());
  event enqueue_unmap_mem_object(cl_mem, void *, 
                                 const wait_list & = wait_list());
  void enqueue_read_image(const image2d &, const size_t, const size_t, size_t, 
                          void *, const wait_list & = wait_list());
  void enqueue_read_image(const image3d &, const size_t, const size_t, size_t, 
                          size_t, void *, const wait_list & = wait_list());
  void enqueue_write_image(const image2d &, const size_t, const size_t, 
                           size_t, const void *, 
                           const wait_list & = wait_list());
  void enqueue_write_image(const image3d &, const size_t, const size_t, 
                           size_t, size_t, const void *, 
                           const wait_list & = wait_list());
  event enqueue_copy_image(const image2d &, const image2d &, const size_t, 
                           const size_t, const size_t, 
                           const wait_list & = wait_list());
  event enqueue_copy_image(const image2d &, const image3d &, const size_t, 
                           const size_t, const size_t, 
                           const wait_list & = wait_list());
  event enqueue_copy_image(const image3d &, const image2d &, const size_t, 
                           const size_t, const size_t, 
                           const wait_list & = wait_list());
  event enqueue_copy_image(const image3d &, const image3d &, const size_t, 
                           const size_t, const size_t, 
                           const wait_list & = wait_list());
  event enqueue_copy_image_to_buffer(const image2d &, const buffer &, 
                                     const size_t, const size_t, size_t, 
                                     const wait_list & = wait_list());
  event enqueue_copy_image_to_buffer(const image3d &, const buffer &, 
                                     const size_t, const size_t, size_t, 
                                     const wait_list & = wait_list());
  event enqueue_copy_buffer_to_image(const buffer &, const image2d &, size_t, 
                                     const size_t, const size_t, 
                                     const wait_list & = wait_list());
  event enqueue_copy_buffer_to_image(const buffer &, const image3d &, size_t, 
                                     const size_t, const size_t, 
                                     const wait_list & = wait_list());
  event enqueue_fill_image(const image2d &, const void *, const size_t, 
                           const size_t, const wait_list & = wait_list());
  event enqueue_fill_image(const image3d &, const void *, const size_t, 
                           const size_t, const wait_list & = wait_list());
  event enqueue_migrate_memory_objects(uint_, const cl_mem *, 
                                       cl_mem_migration_flags, 
                                       const wait_list & = wait_list());
  event enqueue_nd_range_kernel(const kernel &, size_t, const size_t *, 
                                const size_t *, const size_t *, 
                                const wait_list & = wait_list());
  template<size_t N> 
    event enqueue_nd_range_kernel(const kernel &, const extents< N > &, 
                                  const extents< N > &, const extents< N > &, 
                                  const wait_list & = wait_list());
  event enqueue_1d_range_kernel(const kernel &, size_t, size_t, size_t, 
                                const wait_list & = wait_list());
  event enqueue_task(const kernel &, const wait_list & = wait_list());
  event enqueue_native_kernel(void(BOOST_COMPUTE_CL_CALLBACK *user_func)(void *), 
                              void *, size_t, uint_, const cl_mem *, 
                              const void **, const wait_list & = wait_list());
  event enqueue_native_kernel(void(BOOST_COMPUTE_CL_CALLBACK *user_func)(void), 
                              const wait_list & = wait_list());
  void flush();
  void finish();
  void enqueue_barrier();
  void enqueue_barrier(const wait_list &);
  event enqueue_marker();
  event enqueue_marker(const wait_list &);
  void enqueue_svm_memcpy(void *, const void *, size_t, 
                          const wait_list & = wait_list());
  event enqueue_svm_memcpy_async(void *, const void *, size_t, 
                                 const wait_list & = wait_list());
  event enqueue_svm_fill(void *, const void *, size_t, size_t, 
                         const wait_list & = wait_list());
  event enqueue_svm_free(void *, const wait_list & = wait_list());
  void enqueue_svm_map(void *, size_t, cl_map_flags, 
                       const wait_list & = wait_list());
  event enqueue_svm_unmap(void *, const wait_list & = wait_list());
  bool operator==(const command_queue &) const;
  bool operator!=(const command_queue &) const;
};

Description

Command queues provide the interface for interacting with compute devices. The command_queue class provides methods to copy data to and from a compute device as well as execute compute kernels.

Command queues are created for a compute device within a compute context.

For example, to create a context and command queue for the default device on the system (this is the normal set up code used by almost all OpenCL programs):

#include <boost/compute/core.hpp>

// get the default compute device
boost::compute::device device = boost::compute::system::default_device();

// set up a compute context and command queue
boost::compute::context context(device);
boost::compute::command_queue queue(context, device);

The default command queue for the system can be obtained with the system::default_queue() method.

See Also:

buffer, context, kernel

`command_queue` public construct/copy/destruct

```
command_queue();
```
Creates a null command queue.

explicit command_queue(cl_command_queue queue, bool retain = true);

command_queue(const context & context, const device & device, 
              cl_command_queue_properties properties = 0);

Creates a command queue in context for device with properties.

See the documentation for clCreateCommandQueue() for more information.

```
command_queue(const command_queue & other);
```
Creates a new command queue object as a copy of other.
```
command_queue(command_queue && other) noexcept;
```
Move-constructs a new command queue object from other.

command_queue & operator=(const command_queue & other);

Copies the command queue object from other to *this.

command_queue & operator=(command_queue && other) noexcept;

Move-assigns the command queue from other to *this.

```
~command_queue();
```
Destroys the command queue.

See the documentation for clReleaseCommandQueue() for more information.

`command_queue` public member functions

```
cl_command_queue & get() const;
```
Returns the underlying OpenCL command queue.
```
device get_device() const;
```
Returns the device that the command queue issues commands to.
```
context get_context() const;
```
Returns the context for the command queue.
```
template<typename T> T get_info(cl_command_queue_info info) const;
```
Returns information about the command queue.

See the documentation for clGetCommandQueueInfo() for more information.
```
template<int Enum> unspecified get_info() const;
```
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

cl_command_queue_properties get_properties() const;

Returns the properties for the command queue.

void enqueue_read_buffer(const buffer & buffer, size_t offset, size_t size, 
                         void * host_ptr, 
                         const wait_list & events = wait_list());

Enqueues a command to read data from buffer to host memory.

See the documentation for clEnqueueReadBuffer() for more information.

See Also:

copy()

event enqueue_read_buffer_async(const buffer & buffer, size_t offset, 
                                size_t size, void * host_ptr, 
                                const wait_list & events = wait_list());

Enqueues a command to read data from buffer to host memory. The copy will be performed asynchronously.

See the documentation for clEnqueueReadBuffer() for more information.

See Also:

copy_async()

void enqueue_read_buffer_rect(const buffer & buffer, 
                              const size_t buffer_origin, 
                              const size_t host_origin, const size_t region, 
                              size_t buffer_row_pitch, 
                              size_t buffer_slice_pitch, 
                              size_t host_row_pitch, size_t host_slice_pitch, 
                              void * host_ptr, 
                              const wait_list & events = wait_list());

Enqueues a command to read a rectangular region from buffer to host memory.

See the documentation for clEnqueueReadBufferRect() for more information.

	Warning
	This method is only available if the OpenCL version is 1.1 or later.

void enqueue_write_buffer(const buffer & buffer, size_t offset, size_t size, 
                          const void * host_ptr, 
                          const wait_list & events = wait_list());

Enqueues a command to write data from host memory to buffer.

See the documentation for clEnqueueWriteBuffer() for more information.

See Also:

copy()

event enqueue_write_buffer_async(const buffer & buffer, size_t offset, 
                                 size_t size, const void * host_ptr, 
                                 const wait_list & events = wait_list());

Enqueues a command to write data from host memory to buffer. The copy is performed asynchronously.

See the documentation for clEnqueueWriteBuffer() for more information.

See Also:

copy_async()

void enqueue_write_buffer_rect(const buffer & buffer, 
                               const size_t buffer_origin, 
                               const size_t host_origin, const size_t region, 
                               size_t buffer_row_pitch, 
                               size_t buffer_slice_pitch, 
                               size_t host_row_pitch, 
                               size_t host_slice_pitch, void * host_ptr, 
                               const wait_list & events = wait_list());

Enqueues a command to write a rectangular region from host memory to buffer.

See the documentation for clEnqueueWriteBufferRect() for more information.

	Warning
	This method is only available if the OpenCL version is 1.1 or later.

event enqueue_copy_buffer(const buffer & src_buffer, 
                          const buffer & dst_buffer, size_t src_offset, 
                          size_t dst_offset, size_t size, 
                          const wait_list & events = wait_list());

Enqueues a command to copy data from src_buffer to dst_buffer.

See the documentation for clEnqueueCopyBuffer() for more information.

See Also:

copy()

event enqueue_copy_buffer_rect(const buffer & src_buffer, 
                               const buffer & dst_buffer, 
                               const size_t src_origin, 
                               const size_t dst_origin, const size_t region, 
                               size_t buffer_row_pitch, 
                               size_t buffer_slice_pitch, 
                               size_t host_row_pitch, 
                               size_t host_slice_pitch, 
                               const wait_list & events = wait_list());

Enqueues a command to copy a rectangular region from src_buffer to dst_buffer.

See the documentation for clEnqueueCopyBufferRect() for more information.

	Warning
	This method is only available if the OpenCL version is 1.1 or later.

event enqueue_fill_buffer(const buffer & buffer, const void * pattern, 
                          size_t pattern_size, size_t offset, size_t size, 
                          const wait_list & events = wait_list());

Enqueues a command to fill buffer with pattern.

See the documentation for clEnqueueFillBuffer() for more information.

	Warning
	This method is only available if the OpenCL version is 1.2 or later.

See Also:

fill()

void * enqueue_map_buffer(const buffer & buffer, cl_map_flags flags, 
                          size_t offset, size_t size, 
                          const wait_list & events = wait_list());

Enqueues a command to map buffer into the host address space.

See the documentation for clEnqueueMapBuffer() for more information.

event enqueue_unmap_buffer(const buffer & buffer, void * mapped_ptr, 
                           const wait_list & events = wait_list());

Enqueues a command to unmap buffer from the host memory space.

See the documentation for clEnqueueUnmapMemObject() for more information.

event enqueue_unmap_mem_object(cl_mem mem, void * mapped_ptr, 
                               const wait_list & events = wait_list());

Enqueues a command to unmap mem from the host memory space.

See the documentation for clEnqueueUnmapMemObject() for more information.

void enqueue_read_image(const image2d & image, const size_t origin, 
                        const size_t region, size_t row_pitch, 
                        void * host_ptr, 
                        const wait_list & events = wait_list());

Enqueues a command to read data from image to host memory.

See the documentation for clEnqueueReadImage() for more information.

void enqueue_read_image(const image3d & image, const size_t origin, 
                        const size_t region, size_t row_pitch, 
                        size_t slice_pitch, void * host_ptr, 
                        const wait_list & events = wait_list());

Enqueues a command to read data from image to host memory.

See the documentation for clEnqueueReadImage() for more information.

void enqueue_write_image(const image2d & image, const size_t origin, 
                         const size_t region, size_t input_row_pitch, 
                         const void * host_ptr, 
                         const wait_list & events = wait_list());

Enqueues a command to write data from host memory to image.

See the documentation for clEnqueueWriteImage() for more information.

void enqueue_write_image(const image3d & image, const size_t origin, 
                         const size_t region, size_t input_row_pitch, 
                         size_t input_slice_pitch, const void * host_ptr, 
                         const wait_list & events = wait_list());

Enqueues a command to write data from host memory to image.

See the documentation for clEnqueueWriteImage() for more information.

event enqueue_copy_image(const image2d & src_image, const image2d & dst_image, 
                         const size_t src_origin, const size_t dst_origin, 
                         const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_image.

See the documentation for clEnqueueCopyImage() for more information.

event enqueue_copy_image(const image2d & src_image, const image3d & dst_image, 
                         const size_t src_origin, const size_t dst_origin, 
                         const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_image.

See the documentation for clEnqueueCopyImage() for more information.

event enqueue_copy_image(const image3d & src_image, const image2d & dst_image, 
                         const size_t src_origin, const size_t dst_origin, 
                         const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_image.

See the documentation for clEnqueueCopyImage() for more information.

event enqueue_copy_image(const image3d & src_image, const image3d & dst_image, 
                         const size_t src_origin, const size_t dst_origin, 
                         const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_image.

See the documentation for clEnqueueCopyImage() for more information.

event enqueue_copy_image_to_buffer(const image2d & src_image, 
                                   const buffer & dst_buffer, 
                                   const size_t src_origin, 
                                   const size_t region, size_t dst_offset, 
                                   const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_buffer.

See the documentation for clEnqueueCopyImageToBuffer() for more information.

event enqueue_copy_image_to_buffer(const image3d & src_image, 
                                   const buffer & dst_buffer, 
                                   const size_t src_origin, 
                                   const size_t region, size_t dst_offset, 
                                   const wait_list & events = wait_list());

Enqueues a command to copy data from src_image to dst_buffer.

See the documentation for clEnqueueCopyImageToBuffer() for more information.

event enqueue_copy_buffer_to_image(const buffer & src_buffer, 
                                   const image2d & dst_image, 
                                   size_t src_offset, 
                                   const size_t dst_origin, 
                                   const size_t region, 
                                   const wait_list & events = wait_list());

Enqueues a command to copy data from src_buffer to dst_image.

See the documentation for clEnqueueCopyBufferToImage() for more information.

event enqueue_copy_buffer_to_image(const buffer & src_buffer, 
                                   const image3d & dst_image, 
                                   size_t src_offset, 
                                   const size_t dst_origin, 
                                   const size_t region, 
                                   const wait_list & events = wait_list());

Enqueues a command to copy data from src_buffer to dst_image.

See the documentation for clEnqueueCopyBufferToImage() for more information.

event enqueue_fill_image(const image2d & image, const void * fill_color, 
                         const size_t origin, const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to fill image with fill_color.

See the documentation for clEnqueueFillImage() for more information.

	Warning
	This method is only available if the OpenCL version is 1.2 or later.

event enqueue_fill_image(const image3d & image, const void * fill_color, 
                         const size_t origin, const size_t region, 
                         const wait_list & events = wait_list());

Enqueues a command to fill image with fill_color.

See the documentation for clEnqueueFillImage() for more information.

	Warning
	This method is only available if the OpenCL version is 1.2 or later.

event enqueue_migrate_memory_objects(uint_ num_mem_objects, 
                                     const cl_mem * mem_objects, 
                                     cl_mem_migration_flags flags, 
                                     const wait_list & events = wait_list());

Enqueues a command to migrate mem_objects.

See the documentation for clEnqueueMigrateMemObjects() for more information.

	Warning
	This method is only available if the OpenCL version is 1.2 or later.

event enqueue_nd_range_kernel(const kernel & kernel, size_t work_dim, 
                              const size_t * global_work_offset, 
                              const size_t * global_work_size, 
                              const size_t * local_work_size, 
                              const wait_list & events = wait_list());

Enqueues a kernel for execution.

See the documentation for clEnqueueNDRangeKernel() for more information.

template<size_t N> 
  event enqueue_nd_range_kernel(const kernel & kernel, 
                                const extents< N > & global_work_offset, 
                                const extents< N > & global_work_size, 
                                const extents< N > & local_work_size, 
                                const wait_list & events = wait_list());

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

event enqueue_1d_range_kernel(const kernel & kernel, 
                              size_t global_work_offset, 
                              size_t global_work_size, 
                              size_t local_work_size, 
                              const wait_list & events = wait_list());

Convenience method which calls enqueue_nd_range_kernel() with a one-dimensional range.

event enqueue_task(const kernel & kernel, 
                   const wait_list & events = wait_list());

Enqueues a kernel to execute using a single work-item.

See the documentation for clEnqueueTask() for more information.

event enqueue_native_kernel(void(BOOST_COMPUTE_CL_CALLBACK *user_func)(void *), 
                            void * args, size_t cb_args, 
                            uint_ num_mem_objects, const cl_mem * mem_list, 
                            const void ** args_mem_loc, 
                            const wait_list & events = wait_list());

Enqueues a function to execute on the host.

event enqueue_native_kernel(void(BOOST_COMPUTE_CL_CALLBACK *user_func)(void), 
                            const wait_list & events = wait_list());

Convenience overload for enqueue_native_kernel() which enqueues a native kernel on the host with a nullary function.

```
void flush();
```
Flushes the command queue.

See the documentation for clFlush() for more information.
```
void finish();
```
Blocks until all outstanding commands in the queue have finished.

See the documentation for clFinish() for more information.
```
void enqueue_barrier();
```
Enqueues a barrier in the queue.
```
void enqueue_barrier(const wait_list & events);
```
Enqueues a barrier in the queue after events.

Warning

This method is only available if the OpenCL version is 1.2 or later.
```
event enqueue_marker();
```
Enqueues a marker in the queue and returns an event that can be used to track its progress.
```
event enqueue_marker(const wait_list & events);
```
Enqueues a marker after events in the queue and returns an event that can be used to track its progress.

Warning

This method is only available if the OpenCL version is 1.2 or later.
```
void enqueue_svm_memcpy(void * dst_ptr, const void * src_ptr, size_t size, 
                        const wait_list & events = wait_list());
```
Enqueues a command to copy size bytes of data from src_ptr to dst_ptr.

Warning

This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMMemcpy() for more information.

event enqueue_svm_memcpy_async(void * dst_ptr, const void * src_ptr, 
                               size_t size, 
                               const wait_list & events = wait_list());

Enqueues a command to copy size bytes of data from src_ptr to dst_ptr. The operation is performed asynchronously.

	Warning
	This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMMemcpy() for more information.

event enqueue_svm_fill(void * svm_ptr, const void * pattern, 
                       size_t pattern_size, size_t size, 
                       const wait_list & events = wait_list());

Enqueues a command to fill size bytes of data at svm_ptr with pattern.

	Warning
	This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMMemFill() for more information.

```
event enqueue_svm_free(void * svm_ptr, const wait_list & events = wait_list());
```
Enqueues a command to free svm_ptr.

Warning

This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMFree() for more information.

See Also:

svm_free()
```
void enqueue_svm_map(void * svm_ptr, size_t size, cl_map_flags flags, 
                     const wait_list & events = wait_list());
```
Enqueues a command to map svm_ptr to the host memory space.

Warning

This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMMap() for more information.
```
event enqueue_svm_unmap(void * svm_ptr, 
                        const wait_list & events = wait_list());
```
Enqueues a command to unmap svm_ptr from the host memory space.

Warning

This method is only available if the OpenCL version is 2.0 or later.

See the documentation for clEnqueueSVMUnmap() for more information.

bool operator==(const command_queue & other) const;

Returns true if the command queue is the same at other.

bool operator!=(const command_queue & other) const;

Returns true if the command queue is different from other.

Class command_queue

Synopsis

Description

command_queue public construct/copy/destruct

command_queue public member functions

`command_queue` public construct/copy/destruct

`command_queue` public member functions