KhronosGroup / KhronosGroup/OpenCL-Headers
Proposed tidy up of CL_{API,EXT}_{PREFIX,SUFFIX}* definitions
- Dominant language
- C
- Stars
- 766
- Forks
- 273
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 3
Description
These definitions are used to prefix/suffix function declarations, for example to handle deprecation warnings. They currently fall into two categories:
- Per-version definitions (`CL_{API,EXT}_SUFFIX__{EXPERIMENTAL,VERSION*}`). These are always defined to an empty string.
- Per-version deprecation definitions (`CL_EXT_SUFFIX__VERSION_*_DEPRECATED`). These are defined to compiler-specific values that result in warnings being produced when deprecated functions are used. Note that there are no `CL_API_SUFFIX__VERSION_*_DEPRECATED` definitions.
### Problems
- `CL_EXT` and `CL_API` prefixes are used inconsistently and core API function declarations are marked as deprecated with `CL_EXT` definitions
- The distinction doesn't seem to serve any purpose and is confusing
As another data point, extension functions use `CL_API_{CALL,ENTRY}` in their declarations.
### Proposed resolution
- Use `CL_API_{PREFIX,SUFFIX}` for core declarations as well as extensions and remove all `CL_EXT_{PREFIX,SUFFIX}` definitions.
OpenCL-Docs and OpenCL-CLHPP would need changing as well.
### Agreed actions
- [x] Replace all uses of `CL_EXT_{PREFIX,SUFFIX}*` with `CL_API_{PREFIX,SUFFIX}*`
- [ ] Reserve the `CL_API` prefix for internal use
- [ ] Figure out what to do with suffixes on extension functions declarations (minimum required version? what about deprecation?)
Contributor guide
No contributing guide indexed for this repository
Research direction
Review the CL_API and CL_EXT macro definitions and their uses in OpenCL-Headers, then identify the corresponding changes needed in OpenCL-Docs and OpenCL-CLHPP. Verify that CL_EXT_PREFIX/SUFFIX uses are replaced consistently, while documenting the unresolved questions about reserving CL_API and extension-function suffixes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c
- Domain
- api
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100