sdk/2.1/docs/man/work_group_barrier.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">

<refentry>
    <refentryinfo>
        <keywordset>
            <keyword>Synchronization, work_group_barrier, barrier</keyword>
        </keywordset>
    </refentryinfo>

    <refmeta>
        <refentrytitle>work_group_barrier</refentrytitle>

        <refmiscinfo>
            <copyright>
                <year>2007-2013</year>
                <holder>The Khronos Group Inc.
 Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and/or associated documentation files (the
"Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Materials, and to
permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included
in all copies or substantial portions of the Materials.</holder>
            </copyright>
        </refmiscinfo>
        <manvolnum>3</manvolnum>
    </refmeta>

<!-- ================================ SYNOPSIS -->

    <refnamediv id="work_group_barrier">
        <refname>work_group_barrier</refname>

        <refpurpose>
            All work-items in a work-group executing the kernel on a processor must execute this function before any are allowed to continue execution beyond the work_group_barrier.
        </refpurpose>
    </refnamediv>

    <refsynopsisdiv xmlns:xlink="http://www.w3.org/1999/xlink"><title></title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>
                    <link xlink:href="scalarDataTypes.html">void</link>
                    <function>
                        work_group_barrier
                    </function>
                </funcdef>
                <paramdef><link xlink:href="enums.html#cl_mem_fence_flags">cl_mem_fence_flags</link><parameter>flags</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>

        <funcsynopsis>
            <funcprototype>
                <funcdef>
                    <link xlink:href="scalarDataTypes.html">void</link>
                    <function>
                        work_group_barrier
                    </function>
                </funcdef>
                <paramdef><link xlink:href="enums.html#cl_mem_fence_flags">cl_mem_fence_flags</link><parameter>flags</parameter></paramdef>
                <paramdef><link xlink:href="memory_scope.html">memory_scope</link><parameter>scope
</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>

<!-- ================================ DESCRIPTION  -->

    <refsect1 id="description"><title>Description</title>

        <para>
            The built-in function <function>barrier</function> 
            has been renamed <function>work_group_barrier</function>. 
            For backward compatibility, <function>barrier</function> is 
            also supported.
        </para>

        <para>
          All work-items in a work-group executing the kernel on a processor must execute
          this function before any are allowed to continue execution beyond the 
          <function>work_group_barrier</function>.
          This function must be encountered by all work-items in a work-group executing the kernel.
            These rules apply to ND-ranges implemented with uniform and non-uniform 
            work-groups.
        </para>

        <para>
          If <function>work_group_barrier</function> is inside a conditional statement, then all work-items
          must enter the conditional if any work-item enters the conditional statement and
          executes the <function>work_group_barrier</function>.
        </para>

        <para>
          If <function>work_group_barrier</function> is inside a loop, all work-items must execute the
          <function>work_group_barrier</function> for each iteration of the loop before any are allowed
          to continue execution beyond the <function>work_group_barrier</function>.
        </para>

        <para>
            The <function>work_group_barrier</function> function also supports a 
            variant that specifies the memory scope. For the 
            <function>work_group_barrier</function> variant that does not take a 
            memory scope, the <varname>scope</varname> is 
            <code>memory_scope_work_group</code>.
        </para>

        <para>
            The <varname>scope</varname> argument specifies whether the memory 
            accesses of work-items in the work-group to 
            memory address space(s) identified by <varname>flags</varname> become 
            visible to all work-items in the work-group, the 
            device or all SVM devices. 
        </para>

        <para>
            The <function>work_group_barrier</function> function can also be used 
            to specify which memory operations i.e. to global 
            memory, local memory or images become visible to 
            the appropriate memory scope identified by <varname>scope</varname>. 
            The <varname>flags</varname> argument specifies the memory address 
            spaces and can be set to 0 or a 
            combination of the following values ORed together.
            When these flags are OR’ed together the 
            <function>work_group_barrier</function> acts as a combined barrier for 
            all address spaces specified by the flags ordering 
            memory accesses both within and across the 
            specified address spaces.
        </para>

        <para>
            <constant>CLK_LOCAL_MEM_FENCE</constant> - The 
            <function>work_group_barrier</function> function will ensure that all 
            local memory accesses become visible to all 
            workitems in the work-group. Note that the value of 
            <varname>scope</varname> is ignored as the memory scope is always 
            <code>memory_scope_work_group</code>.
        </para>

        <para>
            <constant>CLK_GLOBAL_MEM_FENCE</constant> – The 
            <function>work_group_barrier</function> function ensure that all global 
            memory accesses become visible to the appropriate 
            scope as given by <varname>scope</varname>.
        </para>

        <para>
            <constant>CLK_IMAGE_MEM_FENCE</constant> – The 
            <function>work_group_barrier</function> function will ensure that all 
            image memory accesses become visible to the 
            appropriate scope as given by <varname>scope</varname>. The value of 
            <varname>scope</varname> must be <constant>memory_scope_work_group</constant> or 
            <constant>memory_scope_device</constant>.
        </para>

        <para>
            The values of <varname>flags</varname> and 
            <varname>scope</varname> must be the same for
            all work-items in the work-group.
        </para>

    </refsect1>

<!-- ================================ NOTES
    <refsect1 id="notes"><title>Notes</title>
        <para>

        </para>
    </refsect1>-->
<!-- ================================ EXAMPLE  -->
<!-- DO NOT DELETE IN CASE AN EXAMPLE IS ADDED IN THE FUTURE -->
<!--
    <refsect2 id="example1">
        <title>
            Example
        </title>

        <informaltable frame="none">
            <tgroup cols="1" align="left" colsep="0" rowsep="0">
                <colspec colname="col1" colnum="1" />
                <tbody>
                    <row>
                        <entry>
                            Example goes here - it will be set in "code" type with white space preserved.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
    </refsect2>
-->

<!-- ================================ SPECIFICATION  -->
<!-- Set the "uri" attribute in the <olink /> element to the "named destination" for the PDF page
-->
    <refsect1 id="specification"><title>Specification</title>
        <para>
            <imageobject>
                <imagedata fileref="pdficon_small1.gif" format="gif" />
            </imageobject>

            <olink uri="work_group_barrier">OpenCL Specification</olink>
        </para>
    </refsect1>

<!-- ================================ ALSO SEE  -->
<!-- Enter comma-delimited list of all other pages in the system to link to, using
     <citerefentry /><refentrytitle /> to make it a link. For any case where the text of the link needs to differ
     from the filename of the html file this links to, use the "href" attribute in <citerefentry />. For example:
     <citerefentry href="thatPage"><refentrytitle>clGetDeviceInfo</refentrytitle></citerefentry>


    <refsect1 id="seealso"><title>Also see</title>
        <para>
            <citerefentry href="imageFunctions"><refentrytitle>Image Functions</refentrytitle></citerefentry>
        </para>
    </refsect1>-->

<!-- ============================== COPYRIGHT -->
<!-- Content included from copyright.inc.xsl -->

    <refsect3 id="Copyright"><title></title>
        <imageobject>
                <imagedata fileref="KhronosLogo.jpg" format="jpg" />
        </imageobject>
        <para />
    </refsect3>

 <!-- 29-Oct-2015, C lang ver 2.0 rev 30 -->
</refentry>