add clSetContextDestructorCallback

[bashbaug]

Fixes #187.

This PR adds a new API to register a callback for a context that is called when the context is destroyed.

[kpet]

LGTM with one minor comment. This also begs the (separate) question: do we want to provide an alias to clSetProgramReleaseCallback for consistency? I'm thinking of clSetProgramDestructorCallback.

[bashbaug]

This also begs the (separate) question: do we want to provide an alias to clSetProgramReleaseCallback for consistency? I'm thinking of clSetProgramDestructorCallback.

Since we don't support program scope constructors and destructors in OpenCL 3.0, I think a better thing to do is to deprecate clSetProgramReleaseCallback and add back clSetProgramDestructorCallback if and only if we add functionality that requires it.

[kpet]

Since we don't support program scope constructors and destructors in OpenCL 3.0,

We should clarify this in the spec BTW (Appendix H is pretty clear but the normative section just says "Missing before 2.2" which implies it's supported in 3.0). I've created #347.

I think a better thing to do is to deprecate clSetProgramReleaseCallback and add back clSetProgramDestructorCallback if and only if we add functionality that requires it.

Yes, I was thinking of the end state with the feature added back in, not specifically of 3.0 but I think it makes sense to deprecate in 3.0. I've created #348.

[alycm]

LGTM (the change to man/toctail made me notice other issues, filed that as #350 as nothing to do with this PR).

[keryell]

Since it is similar to some discussion we had in SYCL https://gitlab.khronos.org/sycl/Specification/-/issues/289 I wonder how this feature can be implemented safely.
For example what happens if the OpenCL runtime decide to destruct the context at exit, after main() exits?

[bashbaug]

Interesting discussion, thanks for passing this along. FWIW, I don't think the SYCL proposal (link) is exactly the same as this feature because the proposed SYCL deleter gets called before the SYCL context is deleted, whereas this callback gets called after the OpenCL context is deleted, but there's definitely a fair amount of overlap.

For example what happens if the OpenCL runtime decide to destruct the context at exit, after main() exits?

I think the simplest answer is that this behavior won't be conformant. I'm hand-waving a little, but I imagine we would have a conformance test that ensures the context destructor callback is properly called, similar to this conformance test for clSetMemObjectDestructorCallback:

https://github.com/KhronosGroup/OpenCL-CTS/blob/master/test_conformance/api/test_mem_objects.cpp

Does that sound reasonable?

[bashbaug]

Merging as discussed on the July 16th teleconference.

[keryell]

Yes, there is a difference between when a context is deletable and when it has been actually discarded.
I am curious about the use case.
For example you create a static global C++ object that set up some OpenCL context in the constructor.
Probably it might be too late to be useful if the context destruction call-back is called on this static object destruction...