Description

The following table describes the list of built-in functions that can be used to enqueue a kernel.

When the cl_khr_device_enqueue_local_arg_types extension macro is supported, the Built-in Kernel Enqueue Functions and Built-in Kernel Query Functions described in this section can use any of the built-in OpenCL C scalar or vector integer or floating-point data types, or any user defined type built from these scalar and vector data types, as the pointee type of their arguments. This is indicated by the generic type name gentype in those function signatures.

When the cl_khr_device_enqueue_local_arg_types extension macro is not supported, the pointee type of these functions must be void.

Table 1. Built-in Kernel Enqueue Functions
Built-in Function Description

int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, void (^block)(void))
int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, uint num_events_in_wait_list, const clk_event_t *event_wait_list, clk_event_t *event_ret, void (^block)(void))
int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, void (^block)(local void *, …​), uint size0, …​)
int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, uint num_events_in_wait_list, const clk_event_t *event_wait_list, clk_event_t *event_ret, void (^block)(local void *, …​), uint size0, …​)

If the cl_khr_device_enqueue_local_arg_types extension macro is supported:

int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, void (^block)(local gentype *, …​), uint size0, …​)
int enqueue_kernel(queue_t queue, kernel_enqueue_flags_t flags, const ndrange_t ndrange, uint num_events_in_wait_list, const clk_event_t *event_wait_list, clk_event_t *event_ret, void (^block)(local gentype *, …​), uint size0, …​)

Enqueue the block for execution to queue.

If an event is returned, enqueue_kernel performs an implicit retain on the returned event.

The enqueue_kernel built-in function allows a work-item to enqueue a block. Work-items can enqueue multiple blocks to device queues.

The enqueue_kernel built-in function returns CLK_SUCCESS if the block is enqueued successfully and returns CLK_ENQUEUE_FAILURE otherwise. If the -g compile option is specified in compiler options passed to clCompileProgram or clBuildProgram when compiling or building the parent program, the following errors may be returned instead of CLK_ENQUEUE_FAILURE to indicate why enqueue_kernel failed to enqueue the block:

  • CLK_INVALID_QUEUE if queue is not a valid device queue.

  • CLK_INVALID_NDRANGE if ndrange is not a valid ND-range descriptor or if the program was compiled with -cl-uniform-work-group-size and the local_work_size is specified in ndrange but the global_work_size specified in ndrange is not a multiple of the local_work_size.

  • CLK_INVALID_EVENT_WAIT_LIST if event_wait_list is NULL and num_events_in_wait_list > 0, or if event_wait_list is not NULL and num_events_in_wait_list is 0, or if event objects in event_wait_list are not valid events.

  • CLK_DEVICE_QUEUE_FULL if queue is full.

  • CLK_INVALID_ARG_SIZE if size of local memory arguments is 0.

  • CLK_EVENT_ALLOCATION_FAILURE if event_ret is not NULL and an event could not be allocated.

  • CLK_OUT_OF_RESOURCES if there is a failure to queue the block in queue because of insufficient resources needed to execute the kernel.

See Also

enqueue_marker

Document Notes

For more information, see the OpenCL C Specification

This page is extracted from the OpenCL C Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2026 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0