KhronosGroup / KhronosGroup/OpenCL-Docs

Confirm clUpdateMutableCommandsKHR error behavior

Open
#1,326 3 comments 0 reactions 0 assignees View on GitHub
cl_khr_command_buffer
Dominant language
Python
Stars
420
Forks
131
Avg merge
5d 13h
Merged PRs (30d)
11

Description

Opening this issue to confirm with implementers that the currently specified error behavior of [clUpdateMutableCommandsKHR](https://registry.khronos.org/OpenCL/specs/3.0-unified/html/OpenCL_API.html#clUpdateMutableCommandsKHR) is what we want. In particular that none of the updates to a command-buffer are preserved on error.

> 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

For example, if a user calls the entry-point with a list of update structs: A,B,C, which are iterated though in that order. If C causes an error for whatever reason which is returned to the user via the returned `cl_int`, can implementations rollback updates A & B in all cases?

This behavior is great from the user perspective, as it allows the user to reason about the state of the command-buffer after an error. However, it could involve implementation effort that may be above the guarantees offered by other similar APIs:

* Vulkan - Can't see any wording in the [vkUpdateDescriptorSets description](https://registry.khronos.org/vulkan/specs/latest/man/html/vkUpdateDescriptorSets.html#_description) offering this guarantee.
* Level-Zero - If you pass a pointer chained struct A->B->C to [zeCommandListUpdateMutableCommandsExp](https://oneapi-src.github.io/level-zero-spec/level-zero/latest/core/api.html#zecommandlistupdatemutablecommandsexp) there isn't any wording saying that if C errors that A & B will be rolled back.
* CUDA- `cudaGraphExecKernelNodeSetParams ` operates on nodes individually, but if `cudaGraphExecUpdate` (which operates on whole graph) fails then applications tend to instantiate a new graph rather than do error recovery. Using llama.cpp https://github.com/ggml-org/llama.cpp/blob/69050a11be0ae3e01329f11371ecb6850bdaded5/ggml/src/ggml-cuda/ggml-cuda.cu#L2614-L2615 and GROMACS as examples https://gitlab.com/gromacs/gromacs/-/blob/main/src/gromacs/mdlib/mdgraph_gpu_impl.cu#L392-L394

Contributor guide

Open the contributing guide

Research direction

Start with the clUpdateMutableCommandsKHR wording linked in the issue and compare the rollback guarantee with the cited Vulkan, Level-Zero, and CUDA behavior. The issue is done when implementers reach a decision about preserving updates on error and the specification reflects the agreed behavior.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.