document command buffer APIs that are not thread-safe (KhronosGroup#1345)

Author: bashbaug

api/appendix_a.asciidoc

@@ -30,22 +30,44 @@ how to correctly order operations that change the state of a shared object.
 
 == Multiple Host Threads
 
-All OpenCL API calls are thread-safe footnote:[{fn-thread-safe}] except those
-that modify the state of {cl_kernel_TYPE} objects: {clSetKernelArg},
+OpenCL calls that modify the state of {cl_kernel_TYPE} objects are not
+thread-safe footnote:[{fn-thread-safe}]: {clSetKernelArg},
 {clSetKernelArgSVMPointer}, {clSetKernelExecInfo} and {clCloneKernel}.
-{clSetKernelArg}, {clSetKernelArgSVMPointer}, {clSetKernelExecInfo} and
-{clCloneKernel} are safe to call from any host thread, and safe to call
-re-entrantly so long as concurrent calls to any combination of these API
-calls operate on different {cl_kernel_TYPE} objects.
-The state of the {cl_kernel_TYPE} object is undefined if {clSetKernelArg},
-{clSetKernelArgSVMPointer}, {clSetKernelExecInfo} or {clCloneKernel} are
-called from multiple host threads on the same {cl_kernel_TYPE} object at the same
-time footnote:[{fn-race-condition}].
+These APIs are safe to call from any host thread so long as concurrent calls
+operate on different {cl_kernel_TYPE} objects.
+The state of a {cl_kernel_TYPE} object is undefined if {clSetKernelArg},
+{clSetKernelArgSVMPointer}, {clSetKernelExecInfo} or {clCloneKernel} are called
+from multiple host threads on the same {cl_kernel_TYPE} object at the same time
+footnote:[{fn-race-condition}].
+
+ifdef::cl_khr_command_buffer[]
+Additionally, OpenCL calls that modify the state of {cl_command_buffer_khr_TYPE}
+objects are not thread-safe:
+ifdef::cl_khr_command_buffer_mutable_dispatch[]
+{clFinalizeCommandBufferKHR} and {clUpdateMutableCommandsKHR}.
+endif::cl_khr_command_buffer_mutable_dispatch[]
+ifndef::cl_khr_command_buffer_mutable_dispatch[]
+{clFinalizeCommandBufferKHR}.
+endif::cl_khr_command_buffer_mutable_dispatch[]
+These APIs are safe to call from any host thread so long as concurrent calls
+operate on different {cl_command_buffer_khr_TYPE} objects.
+The state of the {cl_command_buffer_khr_TYPE} object is undefined if
+ifdef::cl_khr_command_buffer_mutable_dispatch[]
+{clFinalizeCommandBufferKHR} or {clUpdateMutableCommandsKHR} are
+endif::cl_khr_command_buffer_mutable_dispatch[]
+ifndef::cl_khr_command_buffer_mutable_dispatch[]
+{clFinalizeCommandBufferKHR} is
+endif::cl_khr_command_buffer_mutable_dispatch[]
+called from multiple host threads on the same {cl_command_buffer_khr_TYPE}
+object at the same time.
+endif::cl_khr_command_buffer[]
+
+All other OpenCL API calls are thread-safe.
 Please note that there are additional limitations as to which OpenCL APIs
-may be called from <<event-objects,OpenCL callback functions>>.
+may be called from <<callback-functions,OpenCL callback functions>>.
 
 The behavior of OpenCL APIs called from an interrupt or signal handler is
-implementation-defined
+implementation-defined.
 
 The OpenCL implementation should be able to create multiple command-queues
 for a given OpenCL context and multiple OpenCL contexts in an application

api/footnotes.asciidoc

@@ -103,7 +103,7 @@ If the platform profile returned is EMBEDDED_PROFILE, then devices that are only
 :fn-race-condition: pass:n[ \
 There is an inherent race condition in the design of OpenCL that occurs between setting a kernel argument and using the kernel with {clEnqueueNDRangeKernel}. \
 Another host thread might change the kernel arguments between when a host thread sets the kernel arguments and then enqueues the kernel, causing the wrong kernel arguments to be enqueued. \
-Rather than attempt to share {cl_kernel_TYPE} objects among multiple host threads, applications are strongly encouraged to make additional {cl_kernel_TYPE} objects for kernel functions for each host thread. \
+Rather than attempt to share {cl_kernel_TYPE} objects among multiple host threads, applications are strongly encouraged to make additional {cl_kernel_TYPE} objects for each host thread. \
 ]
 
 :fn-readimageh: pass:n[ \

api/glossary.asciidoc

@@ -793,8 +793,7 @@ Thread-safe ::
     by multiple _host_ threads.
     OpenCL API calls that are _thread-safe_ allow an application to call
     these functions in multiple _host_ threads without having to implement
-    mutual exclusion across these _host_ threads i.e. they are also
-    re-entrant-safe.
+    mutual exclusion across these _host_ threads.
 
 Undefined ::
     The behavior of an OpenCL API call, built-in function used inside a

api/opencl_runtime_layer.asciidoc

@@ -5863,6 +5863,7 @@ Otherwise, it returns one of the following errors:
   * {CL_OUT_OF_HOST_MEMORY} if there is a failure to allocate resources
     required by the OpenCL implementation on the host.
 
+[[callback-functions]]
 [NOTE]
 ====
 When the user callback function is called by the implementation, the