KhronosGroup / KhronosGroup/OpenCL-Docs
Confirm clUpdateMutableCommandsKHR error behavior
- 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
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