blob: 0dadab0d853258789ce521818649981c6cffebad [file] [log] [blame]
<!-- for inclusion with the relevant functions -->
<bridgehead>Multiple Host Threads</bridgehead>
<para>
<!-- from the spec's glossary --> An OpenCL API call is considered to be
<emphasis>thread-safe</emphasis> if the internal state as managed by OpenCL remains
consistent when called simultaneously by multiple <emphasis>host</emphasis> threads.
OpenCL API calls that are <emphasis>thread-safe</emphasis> allow an application to
call these functions in multiple <emphasis>host</emphasis> threads without having to
implement mutual exclusion across these <emphasis>host</emphasis> threads i.e. they
are also re-entrant-safe.
</para>
<para>
<!-- section A.2 -->
All OpenCL API calls are thread-safe except those that modify the state of cl_kernel objects:
<citerefentry><refentrytitle>clSetKernelArg</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>clSetKernelArgSVMPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>clSetKernelExecInfo</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>clCloneKernel</refentrytitle></citerefentry>.
</para>
<para>
<citerefentry><refentrytitle>clSetKernelArg</refentrytitle></citerefentry> ,
<citerefentry><refentrytitle>clSetKernelArgSVMPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>clSetKernelExecInfo</refentrytitle></citerefentry> and
<citerefentry><refentrytitle>clCloneKernel</refentrytitle></citerefentry>
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 objects. The state of the cl_kernel
object is undefined if
<citerefentry><refentrytitle>clSetKernelArg</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>clSetKernelArgSVMPointer</refentrytitle></citerefentry>,
<citerefentry><refentrytitle>clSetKernelExecInfo</refentrytitle></citerefentry> or
<citerefentry><refentrytitle>clCloneKernel</refentrytitle></citerefentry>
are called from multiple host threads on the same cl_kernel object at the same
time. Please note that there are additional limitations as to which OpenCL APIs may be called
from OpenCL callback functions -- please see section 5.11.
</para>
<para>
The behavior of OpenCL APIs called from an interrupt or signal handler is
implementation-defined.
</para>
<para>
<!-- section A.2, footnote --> There is an inherent race condition in the
design of OpenCL that occurs between setting a kernel argument and using the kernel
with
<citerefentry><refentrytitle>clEnqueueNDRangeKernel</refentrytitle></citerefentry>.
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 <type>cl_kernel</type> objects among multiple host
threads, applications are strongly encouraged to make additional <type>cl_kernel</type> objects
for kernel functions for each host thread.
</para>
<!-- 27-Oct-2015, API ver 2.1 rev. 19 -->