C Specification

To modify the configuration of mutable-command handles returned during command_buffer recording, updating the behavior of those commands in future enqueues of command_buffer, call the function

// Provided by cl_khr_command_buffer_mutable_dispatch
cl_int clUpdateMutableCommandsKHR(
    cl_command_buffer_khr command_buffer,
    cl_uint num_configs,
    const cl_command_buffer_update_type_khr* config_types,
    const void** configs);
clUpdateMutableCommandsKHR is provided by the cl_khr_command_buffer_mutable_dispatch extension.

Parameters

  • command_buffer refers to a valid command-buffer object.

  • num_configs Number of elements in the config_types and config arrays.

  • config_types An array of length num_configs with each element identifying the type of each config in configs at the same array index.

  • configs An array of length num_configs containing structs which define how a mutable-command handle in command_buffer is to be updated, each of which is interpreted using config_types at the same index with the mapping defined in the Mutable Command Update Structs section.

Description

clUpdateMutableCommandsKHR returns CL_SUCCESS if all the mutable-command objects were updated successfully. Otherwise, none of the updates to mutable-command objects are preserved and one of the errors below is returned:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_OPERATION if command_buffer has not been finalized.

  • CL_INVALID_OPERATION if command_buffer was not created with the CL_COMMAND_BUFFER_MUTABLE_KHR flag.

  • CL_INVALID_VALUE if config_types is NULL and num_configs > 0, or config_types is not NULL and num_configs is 0.

  • CL_INVALID_VALUE if configs is NULL and num_configs > 0, or configs is not NULL and num_configs is 0.

  • CL_INVALID_VALUE if any element of config_types is not a valid cl_command_buffer_update_type_khr enum.

  • CL_INVALID_VALUE if any element of configs 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.

Using this function when command_buffer is in the pending state and not created with the CL_COMMAND_BUFFER_SIMULTANEOUS_USE_KHR flag causes undefined behavior.

Performant usage is to call clUpdateMutableCommandsKHR only when the desired state of all commands is known, rather than iteratively updating each command individually.

If the command buffer has been created with CL_MUTABLE_DISPATCH_ASSERT_NO_ADDITIONAL_WORK_GROUPS_KHR, or the updated ND-range command has been recorded with this flag, and the ND-range parameters are updated so that the new number of work-groups exceeds the number when the ND-range command was recorded, the behavior is undefined.

If configs is non-NULL, then for any cl_mutable_dispatch_config_khr element of the array the errors defined by clEnqueueNDRangeKernel, clSetKernelExecInfo, clSetKernelArg, and clSetKernelArgSVMPointer are returned by clUpdateMutableCommandsKHR if any of the struct elements are set to an invalid value. Additionally, the following errors are returned if any cl_mutable_dispatch_config_khr element of the array violates the defined conditions:

  • CL_INVALID_MUTABLE_COMMAND_KHR if command is not a valid mutable command object returned from clCommandNDRangeKernelKHR, or created from command_buffer.

  • CL_INVALID_OPERATION if the values of local_work_size and/or global_work_size result in a change to work-group uniformity.

  • CL_INVALID_OPERATION if work_dim is not zero and different from the work_dim set on command recording.

  • CL_INVALID_OPERATION if the CL_MUTABLE_DISPATCH_GLOBAL_OFFSET_KHR property was not set on command recording and global_work_offset is not NULL.

  • CL_INVALID_OPERATION if the CL_MUTABLE_DISPATCH_GLOBAL_SIZE_KHR property was not set on command recording and global_work_size is not NULL.

  • CL_INVALID_OPERATION if the CL_MUTABLE_DISPATCH_LOCAL_SIZE_KHR property was not set on command recording and local_work_size is not NULL.

  • CL_INVALID_OPERATION if the CL_MUTABLE_DISPATCH_ARGUMENTS_KHR property was not set on command recording and num_args or num_svm_args is non-zero.

  • CL_INVALID_OPERATION if the CL_MUTABLE_DISPATCH_EXEC_INFO_KHR property was not set on command recording and num_exec_infos is non-zero.

  • CL_INVALID_VALUE if arg_list is NULL and num_args > 0, or arg_list is not NULL and num_args is 0.

  • CL_INVALID_VALUE if arg_svm_list is NULL and num_svm_args > 0, or arg_svm_list is not NULL and num_svm_args is 0.

  • CL_INVALID_VALUE if exec_info_list is NULL and num_exec_infos > 0, or exec_info_list is not NULL and num_exec_infos is 0.

See Also

cl_command_buffer_khr, cl_command_buffer_update_type_khr, cl_khr_command_buffer_mutable_dispatch, 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-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0