KhronosGroup / KhronosGroup/OpenCL-Headers

Proposed tidy up of CL_{API,EXT}_{PREFIX,SUFFIX}* definitions

Open
#153 6 comments 0 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.