| |
| <!-- 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 --> |
| |