Clarify on Comparability & Uniqueness of OpenCL Objects

[Snektron]

In the current version of the OpenCL specification, there is no guarantee on the comparability of two OpenCL handles. It seems that in typical implementations, a handle is simply a pointer to an internal structure containing the particularities of the object, and so in practise comparing two handles for equality will yield the desired results. Technically, however, an object could have multiple handles that internally map to the same object. This case is of particular interest in clGet*Info calls which fetch a handle to the parent of the object, allowing the implementation to return a handle with a different value. For instance, this makes it unclear if the following snippet is valid at all, and what the result should be:

cl_context ctx = clCreateContext(...);
cl_command_queue queue = clCreateQueueCommand(ctx, ...);
cl_context parent;
clGetCommandQueueInfo(queue, CL_QUEUE_CONTEXT, sizeof(cl_context), &parent, NULL);
puts(parent == ctx ? "same" : "different");

Assuming that object handles are indeed comparable, and that each object should have a unique handle during its lifetime, the issue of reusing handles comes up. For instance, the following snippet is invalid, but releases ctx_b in some implementations:

cl_context ctx_a = clCreateContext(...);
clReleaseContext(ctx_a);

cl_context ctx_b = clCreateContext(...);
clReleaseContext(ctx_a);

While these issues are not very significant for the validity of typical OpenCL programs, clarifying them should serve to help improve diagnostic layers that catch issues in invalid programs. Therefore, we propose the following wording:

• In the definition of Handle in chapter 2 (Glossary):

  Handle
  An opaque type that references an object allocated by OpenCL. Any operation on an object occurs by reference to that objects handle. Each object must have a unique handle value during the course of its lifetime. Handle values may be, but are not required to be re-used by an implementation.

[bashbaug]

Very minor editorial suggestions (one of these is not new):

• objects -> object's
• add a comma after: required to be

Handle
An opaque type that references an object allocated by OpenCL. Any operation on an object occurs by reference to that object's handle. Each object must have a unique handle value during the course of its lifetime. Handle values may be, but are not required to be, re-used by an implementation.

[bashbaug]

Since PR #802 is merged I think we can close this now?

[Snektron]

Yes. What about CTS coverage?

[bashbaug]

Yes. What about CTS coverage?

Good question. We should either add it, or add a CTS issue so it's less likely to slip through the cracks.

[bashbaug]

I added KhronosGroup/OpenCL-CTS#1485 to track CTS coverage for this update.