KhronosGroup / KhronosGroup/OpenCL-Docs
clarify behavior of clLinkProgram when linking fails
- Dominant language
- Python
- Stars
- 420
- Forks
- 131
- Avg merge
- 5d 13h
- Merged PRs (30d)
- 11
Description
Creating an issue based on discussion in PR https://github.com/KhronosGroup/OpenCL-Docs/pull/798.
The behavior of `clLinkProgram` does not seem to be precisely described and as a result implementations are behaving differently. We need to determine what we can fix now, and if we cannot fix everything, what we would like to fix in a future spec version.
Notes:
* `clLinkProgram` creates a new program object, unlike `clCompileProgram` and `clBuildProgram`, which operate on program objects that have already been created.
* `clLinkProgram` may (or may not!) link asynchronously if a callback function _pfn_notify_ is passed to the function.
* The spec defines conditions when "the linking operation can begin": if the context, list of devices, input programs and linker options specified are all valid and appropriate host and device resources needed to perform the link are available.
Some things we need to decide where implementations are behaving differently are:
1. What are the situations when `clLinkProgram` must return a `NULL` program object and an error code in _errcode_ret_? Are these all of the cases where "the linking operation cannot begin", or are there other cases that must return a `NULL` program object and an error code also?
2. Are there scenarios when `clLinkProgram` may return both a new non-`NULL` program object and an error code in _errcode_ret_? Or, if an error code is generated, will `clLinkProgram` also return a `NULL` program object?
3. If a callback function is provided, will it always be called, even if an error occurs? If an error occurs, what program object is passed to the callback function?
(If you're curious to see how your implementation behaves, I put my tester here: https://github.com/bashbaug/SimpleOpenCLSamples/tree/link-program-error-behavior/samples/99_linkprogramerror.)
Contributor guide
Research direction
Start with the discussion in PR https://github.com/KhronosGroup/OpenCL-Docs/pull/798 and review the clLinkProgram behavior described in this issue. Run or inspect the linked SimpleOpenCLSamples tester at samples/99_linkprogramerror to compare implementation behavior. Done means deciding the NULL-object, error-code, and callback rules and updating the relevant specification text.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100