Status of clSetCommandQueueProperty

[bashbaug]

See: KhronosGroup/OpenCL-CTS#1182

The current OpenCL spec says that clSetCommandQueueProperty is deprecated, where the glossary definition of deprecated is:

Existing features are marked as deprecated if their usage is not recommended as that feature is being de-emphasized, superseded and may be removed from a future version of the specification.

This was an addition to the OpenCL 3.0 spec. Prior to OpenCL 3.0, the last version of the OpenCL spec to include clSetCommandQueueProperty was the OpenCL 1.0 spec, and the API was removed from the OpenCL 1.1 spec with the comment:

The following features in OpenCL 1.0 are deprecated:

• The clSetCommandQueueProperty API is no longer supported in OpenCL 1.1.

The current OpenCL headers have the comment:

https://github.com/KhronosGroup/OpenCL-Headers/blob/v2021.04.29/CL/cl.h#L1845

#ifdef CL_USE_DEPRECATED_OPENCL_1_0_APIS
    /*
     *  WARNING:
     *     This API introduces mutable state into the OpenCL implementation. It has been REMOVED
     *  to better facilitate thread safety.  The 1.0 API is not thread safe. It is not tested by the
     *  OpenCL 1.1 conformance test, and consequently may not work or may not work dependably.
     *  It is likely to be non-performant. Use of this API is not advised. Use at your own risk.
     *
     *  Software developers previously relying on this API are instructed to set the command queue
     *  properties when creating the queue, instead.
     */
    extern CL_API_ENTRY cl_int CL_API_CALL
    clSetCommandQueueProperty(cl_command_queue              command_queue,
                              cl_command_queue_properties   properties,
                              cl_bool                       enable,
                              cl_command_queue_properties * old_properties) CL_API_SUFFIX__VERSION_1_0_DEPRECATED;
#endif /* CL_USE_DEPRECATED_OPENCL_1_0_APIS */

What is the status of clSetCommandQueueProperty?

• Is it deprecated using the definition described in the spec glossary, in which case it should be tested and functional even if its use is not recommended?
• Or, is it removed or otherwise unsupported, in which case it may not be functional?
  • If this is the case, what level of CTS testing is appropriate for this API?

[bashbaug]

Discussed in the September 19th teleconference.

In short, we made a mistake when we unified the specification for all OpenCL versions in OpenCL 3.0: We added the clSetCommandQueueProperty API back into the spec, which was the right thing to do, but we incorrectly said that it was deprecated starting from OpenCL 1.1, whereas we should have said that it was removed starting from OpenCL 1.1. This removal is documented in the OpenCL 1.1 spec, page 385, and in the headers, as describe above.

Proposed resolution is to correct the OpenCL 3.0-unified specification to say that clSetCommandQueueProperty was removed starting from OpenCL 1.1 instead. We will document a recommended behavior for OpenCL 3.0 implementations (probably returning an error). This is a more accurate description of the state of the world today, since many implementations do not implement this API, and there are no CTS tests to verify that other implementations work as described. This also avoids some nasty interactions with command buffers that inherit properties from command queues.