KhronosGroup / KhronosGroup/OpenCL-Docs
clEnqueueMarkerWithWaitList output event handling is ambiguous
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
The issue actually started [here](https://gitlab.freedesktop.org/mesa/mesa/-/issues/10664), please take a look to the simple reproducer code.
The code does the following:
- Create an user event and set it as CL_COMPLETE, called `wait_event`
- Create a marker synced with that `wait_event`, called `trigger`
- Create a third event to be set as complete by a callback, called `finish`
- Set a callback on `trigger`, with the function that will set `finish` as `CL_COMPLETE`
- Wait for `finish`
According to the documentation, it is unclear if the callback will be called, or it is required to call `clFlush()`. Indeed, on [clEnqueueMarkerWithWaitList() ref page](https://registry.khronos.org/OpenCL/sdk/3.0/docs/man/html/clEnqueueMarkerWithWaitList.html) it says:
"The marker command either waits for a list of events to complete, or if the list is empty it waits for all commands previously enqueued in command_queue to complete before it completes."
Which says that the "dependencies" shall complete before the marker completes, but do not state anything about when that will happen, i.e. will that implicitly happen or a `clFlush()` call is required?. It also says that
"This command returns an event which can be waited on, i.e. this event can be waited on to insure that all events either in the event_wait_list or all previously enqueued commands, queued before this command to command_queue, have completed."
Which clearly indicates that the event can be used on a `clWaitForEvents()` call, but it is not stating nothing about non blocking operations (like callbacks or enqueues)
Finally, on [clFlush() ref page](https://registry.khronos.org/OpenCL/sdk/3.0/docs/man/html/clFlush.html) it says:
"To use event objects that refer to commands enqueued in a command-queue as event objects to wait on by commands enqueued in a different command-queue, the application must call a clFlush or any blocking commands that perform an implicit flush of the command-queue where the commands that refer to these event objects are enqueued."
Which clearly states that `clFlush()` is required if it involves several queues, but unfortunately is not addressing this particular situation.
P.S. I suppose the same can be applied to `clEnqueueBarrierWithWaitList()`
Contributor guide
Research direction
Start with the simple reproducer in the linked Mesa issue and compare its behavior with the cited clEnqueueMarkerWithWaitList() and clFlush() reference pages. Clarify whether callbacks or other nonblocking operations require an explicit flush in this situation, and state whether the same guidance applies to clEnqueueBarrierWithWaitList().
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100