C Specification

To query a suggested local work size for a kernel object, call the function

// Provided by CL_VERSION_3_1
cl_int clGetKernelSuggestedLocalWorkSize(
    cl_command_queue command_queue,
    cl_kernel kernel,
    cl_uint work_dim,
    const size_t* global_work_offset,
    const size_t* global_work_size,
    size_t* suggested_local_work_size);
clGetKernelSuggestedLocalWorkSize is missing before version 3.1.

or the equivalent

// Provided by cl_khr_suggested_local_work_size
cl_int clGetKernelSuggestedLocalWorkSizeKHR(
    cl_command_queue command_queue,
    cl_kernel kernel,
    cl_uint work_dim,
    const size_t* global_work_offset,
    const size_t* global_work_size,
    size_t* suggested_local_work_size);
clGetKernelSuggestedLocalWorkSizeKHR is provided by the cl_khr_suggested_local_work_size extension.

Parameters

  • command_queue specifies the command-queue and device for the query.

  • kernel specifies the kernel object and kernel arguments for the query. The OpenCL context associated with kernel and command_queue must the same.

  • work_dim specifies the number of work dimensions in the input global work offset and global work size, and the output suggested local work size.

  • global_work_offset can be used to specify an array of at least work_dim global ID offset values for the query. This is optional and may be NULL to indicate there is no global ID offset.

  • global_work_size is an array of at least work_dim values describing the global work size for the query.

  • suggested_local_work_size is an output array of at least work_dim values that will contain the result of the query.

Description

The returned suggested local work size is expected to match the local work size that would be chosen if the specified kernel object, with the same kernel arguments, were enqueued into the specified command-queue with the specified global work size, specified global work offset, and with a NULL local work size.

clGetKernelSuggestedLocalWorkSize returns CL_SUCCESS if the query executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_COMMAND_QUEUE

    • if command_queue is not a valid host command-queue

  • CL_INVALID_KERNEL

    • if kernel is not a valid kernel

  • CL_INVALID_PROGRAM_EXECUTABLE

    • if there is no successfully built program executable available for the device associated with command_queue

  • CL_INVALID_CONTEXT

    • if the context associated with command_queue and kernel are not the same

  • CL_INVALID_KERNEL_ARGS

    • if any kernel arguments for kernel have not been set

  • CL_INVALID_WORK_DIMENSION

    • if work_dim is not valid for the device associated with command_queue (is greater than the value returned for CL_DEVICE_MAX_WORK_ITEM_DIMENSIONS)

  • CL_INVALID_GLOBAL_OFFSET

    • if global_work_offset is not NULL. This error condition does not apply when the device associated with command_queue supports OpenCL 1.1 or newer.

    • if the value specified in global_work_size plus the corresponding value in global_work_offset for any dimensions is greater than the maximum value representable by size_t on the device associated with command_queue

  • CL_INVALID_GLOBAL_WORK_SIZE

    • if global_work_size is NULL

    • if any of the values specified in global_work_size[0], …​ global_work_size[work_dim - 1] are zero

    • if any of the values specified in global_work_size[0], …​ global_work_size[work_dim - 1] exceed the maximum value representable by size_t on the device associated with command_queue

  • CL_MISALIGNED_SUB_BUFFER_OFFSET

    • if a kernel argument for kernel is a sub-buffer object and the offset specified when the sub-buffer object is created is not aligned to CL_DEVICE_MEM_BASE_ADDR_ALIGN for the device associated with command_queue. This error code is missing before version 1.1.

  • CL_INVALID_IMAGE_SIZE

    • if a kernel argument for kernel is an image and the dimensions of the image, such as the image width or image height, are not supported by the device associated with command_queue

  • CL_IMAGE_FORMAT_NOT_SUPPORTED

    • if a kernel argument for kernel is an image and the format of the image, such as the image channel order or image channel data type, are not supported by the device associated with command_queue

  • CL_INVALID_OPERATION

    • if SVM pointers are set as arguments for kernel and the device associated with command_queue does not support SVM

    • if system pointers are set as arguments for kernel and the device associated with command_queue does not support fine-grain system SVM

  • CL_INVALID_VALUE

    • if suggested_local_work_size is NULL

  • CL_OUT_OF_RESOURCES

    • if there is a failure to allocate resources required by the OpenCL implementation on the device

  • CL_OUT_OF_HOST_MEMORY

    • if there is a failure to allocate resources required by the OpenCL implementation on the host

These error conditions are consistent with error conditions for clEnqueueNDRangeKernel.

See Also

CL_VERSION_3_1, cl_command_queue, cl_kernel, cl_khr_suggested_local_work_size, cl_uint

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL 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