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

[kpet]

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

• 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?)

[bashbaug]

Switching to the CL_API_{PREFIX,SUFFIX} vs. CL_EXT_{PREFIX,SUFFIX} makes sense to me, +1.

Is there a usage model for the CL_API_SUFFIX__{EXPERIMENTAL,VERSION*} definitions or can they be removed?

[kpet]

Ok, I'll do that.

Is there a usage model for the CL_API_SUFFIX__{EXPERIMENTAL,VERSION*} definitions or can they be removed?

I actually started using them in #154 (which I'd like to get in before the tidy up as they would conflict).

[bashbaug]

I was actually looking at #154 which prompted my question. Right now it looks like we have a possible use for prefix and suffix defiitions generally (for things like #154), and for prefix and suffix defiitions for deprecations for specific versions, but I don't currently see a need for prefix and suffix definitions for specific versions that are not tied to deprecations.

If so, would be fine with:

• General prefix and suffix definitions that are not version-specific and are used for most APIs. These would replace the current version-specific prefix and suffix definitions for non-deprecated APIs.
• Version-specific prefix and suffix definitions for APIs that were deprecated in a specific version.

[kpet]

Even if we don't have a use for them at the moment I think I'd rather we keep the version-specific definitions as they enable to centrally manage this should we need to in the future. All the annotation work has been done and I think the burden to keep them is minimal.

If someone strongly disagrees though I'm open to making the change as a follow-up PR.

[bashbaug]

I think I'd rather we keep the version-specific definitions as they enable to centrally manage this should we need to in the future. All the annotation work has been done and I think the burden to keep them is minimal.

OK, no problem, makes sense.

The version-specific prefixes and suffixes that bother me the most are the ones on extension APIs in the extension headers: Some APIs have them, some APIs don't, and for the APIs that do have them the version appears to be chosen fairly arbitrarily. Would it make sense to have a non-versioned extension prefix and suffix definition? I don't think the answer is to drop the extension prefixes and suffixes entirely if we're going to support user-supplied prefix and suffix definitions, although extension APIs are a little strange so perhaps this needs a bit more thought.

[kpet]

I agree extension function declarations will need some special care. The first idea that comes to mind is to use the minimum required version (which could at least be 1.0 in all cases). Deprecation of extension function declarations is probably worth a discussion as well. I've added an item to the checklist I added at the end of the description.