| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being "Funding Free Software", the Front-Cover |
| Texts being (a) (see below), and with the Back-Cover Texts being (b) |
| (see below). A copy of the license is included in the section entitled |
| "GNU Free Documentation License". |
| |
| (a) The FSF's Front-Cover Text is: |
| |
| A GNU Manual |
| |
| (b) The FSF's Back-Cover Text is: |
| |
| You have freedom to copy and modify this GNU Manual, like GNU |
| software. Copies published by the Free Software Foundation raise |
| funds for GNU development. --> |
| <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ --> |
| <head> |
| <title>Using the GNU Compiler Collection (GCC): __sync Builtins</title> |
| |
| <meta name="description" content="Using the GNU Compiler Collection (GCC): __sync Builtins"> |
| <meta name="keywords" content="Using the GNU Compiler Collection (GCC): __sync Builtins"> |
| <meta name="resource-type" content="document"> |
| <meta name="distribution" content="global"> |
| <meta name="Generator" content="makeinfo"> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> |
| <link href="index.html#Top" rel="start" title="Top"> |
| <link href="Option-Index.html#Option-Index" rel="index" title="Option Index"> |
| <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> |
| <link href="C-Extensions.html#C-Extensions" rel="up" title="C Extensions"> |
| <link href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" rel="next" title="__atomic Builtins"> |
| <link href="Offsetof.html#Offsetof" rel="prev" title="Offsetof"> |
| <style type="text/css"> |
| <!-- |
| a.summary-letter {text-decoration: none} |
| blockquote.smallquotation {font-size: smaller} |
| div.display {margin-left: 3.2em} |
| div.example {margin-left: 3.2em} |
| div.indentedblock {margin-left: 3.2em} |
| div.lisp {margin-left: 3.2em} |
| div.smalldisplay {margin-left: 3.2em} |
| div.smallexample {margin-left: 3.2em} |
| div.smallindentedblock {margin-left: 3.2em; font-size: smaller} |
| div.smalllisp {margin-left: 3.2em} |
| kbd {font-style:oblique} |
| pre.display {font-family: inherit} |
| pre.format {font-family: inherit} |
| pre.menu-comment {font-family: serif} |
| pre.menu-preformatted {font-family: serif} |
| pre.smalldisplay {font-family: inherit; font-size: smaller} |
| pre.smallexample {font-size: smaller} |
| pre.smallformat {font-family: inherit; font-size: smaller} |
| pre.smalllisp {font-size: smaller} |
| span.nocodebreak {white-space:nowrap} |
| span.nolinebreak {white-space:nowrap} |
| span.roman {font-family:serif; font-weight:normal} |
| span.sansserif {font-family:sans-serif; font-weight:normal} |
| ul.no-bullet {list-style: none} |
| --> |
| </style> |
| |
| |
| </head> |
| |
| <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> |
| <a name="g_t_005f_005fsync-Builtins"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" accesskey="n" rel="next">__atomic Builtins</a>, Previous: <a href="Offsetof.html#Offsetof" accesskey="p" rel="prev">Offsetof</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| <hr> |
| <a name="Legacy-_005f_005fsync-Built_002din-Functions-for-Atomic-Memory-Access"></a> |
| <h3 class="section">6.51 Legacy __sync Built-in Functions for Atomic Memory Access</h3> |
| |
| <p>The following built-in functions |
| are intended to be compatible with those described |
| in the <cite>Intel Itanium Processor-specific Application Binary Interface</cite>, |
| section 7.4. As such, they depart from the normal GCC practice of using |
| the ‘<samp>__builtin_</samp>’ prefix, and further that they are overloaded such that |
| they work on multiple types. |
| </p> |
| <p>The definition given in the Intel documentation allows only for the use of |
| the types <code>int</code>, <code>long</code>, <code>long long</code> as well as their unsigned |
| counterparts. GCC allows any integral scalar or pointer type that is |
| 1, 2, 4 or 8 bytes in length. |
| </p> |
| <p>Not all operations are supported by all target processors. If a particular |
| operation cannot be implemented on the target processor, a warning is |
| generated and a call an external function is generated. The external |
| function carries the same name as the built-in version, |
| with an additional suffix |
| ‘<samp>_<var>n</var></samp>’ where <var>n</var> is the size of the data type. |
| </p> |
| |
| <p>In most cases, these built-in functions are considered a <em>full barrier</em>. |
| That is, |
| no memory operand is moved across the operation, either forward or |
| backward. Further, instructions are issued as necessary to prevent the |
| processor from speculating loads across the operation and from queuing stores |
| after the operation. |
| </p> |
| <p>All of the routines are described in the Intel documentation to take |
| “an optional list of variables protected by the memory barrier”. It’s |
| not clear what is meant by that; it could mean that <em>only</em> the |
| following variables are protected, or it could mean that these variables |
| should in addition be protected. At present GCC ignores this list and |
| protects all variables that are globally accessible. If in the future |
| we make some use of this list, an empty list will continue to mean all |
| globally accessible variables. |
| </p> |
| <dl compact="compact"> |
| <dt><code><var>type</var> __sync_fetch_and_add (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_fetch_and_sub (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_fetch_and_or (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_fetch_and_and (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_fetch_and_xor (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_fetch_and_nand (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005ffetch_005fand_005fadd"></a> |
| <a name="index-_005f_005fsync_005ffetch_005fand_005fsub"></a> |
| <a name="index-_005f_005fsync_005ffetch_005fand_005for"></a> |
| <a name="index-_005f_005fsync_005ffetch_005fand_005fand"></a> |
| <a name="index-_005f_005fsync_005ffetch_005fand_005fxor"></a> |
| <a name="index-_005f_005fsync_005ffetch_005fand_005fnand"></a> |
| <p>These built-in functions perform the operation suggested by the name, and |
| returns the value that had previously been in memory. That is, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">{ tmp = *ptr; *ptr <var>op</var>= value; return tmp; } |
| { tmp = *ptr; *ptr = ~(tmp & value); return tmp; } // nand |
| </pre></div> |
| |
| <p><em>Note:</em> GCC 4.4 and later implement <code>__sync_fetch_and_nand</code> |
| as <code>*ptr = ~(tmp & value)</code> instead of <code>*ptr = ~tmp & value</code>. |
| </p> |
| </dd> |
| <dt><code><var>type</var> __sync_add_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_sub_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_or_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_and_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_xor_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dt><code><var>type</var> __sync_nand_and_fetch (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005fadd_005fand_005ffetch"></a> |
| <a name="index-_005f_005fsync_005fsub_005fand_005ffetch"></a> |
| <a name="index-_005f_005fsync_005for_005fand_005ffetch"></a> |
| <a name="index-_005f_005fsync_005fand_005fand_005ffetch"></a> |
| <a name="index-_005f_005fsync_005fxor_005fand_005ffetch"></a> |
| <a name="index-_005f_005fsync_005fnand_005fand_005ffetch"></a> |
| <p>These built-in functions perform the operation suggested by the name, and |
| return the new value. That is, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">{ *ptr <var>op</var>= value; return *ptr; } |
| { *ptr = ~(*ptr & value); return *ptr; } // nand |
| </pre></div> |
| |
| <p><em>Note:</em> GCC 4.4 and later implement <code>__sync_nand_and_fetch</code> |
| as <code>*ptr = ~(*ptr & value)</code> instead of |
| <code>*ptr = ~*ptr & value</code>. |
| </p> |
| </dd> |
| <dt><code>bool __sync_bool_compare_and_swap (<var>type</var> *ptr, <var>type</var> oldval, <var>type</var> newval, ...)</code></dt> |
| <dt><code><var>type</var> __sync_val_compare_and_swap (<var>type</var> *ptr, <var>type</var> oldval, <var>type</var> newval, ...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005fbool_005fcompare_005fand_005fswap"></a> |
| <a name="index-_005f_005fsync_005fval_005fcompare_005fand_005fswap"></a> |
| <p>These built-in functions perform an atomic compare and swap. |
| That is, if the current |
| value of <code>*<var>ptr</var></code> is <var>oldval</var>, then write <var>newval</var> into |
| <code>*<var>ptr</var></code>. |
| </p> |
| <p>The “bool” version returns true if the comparison is successful and |
| <var>newval</var> is written. The “val” version returns the contents |
| of <code>*<var>ptr</var></code> before the operation. |
| </p> |
| </dd> |
| <dt><code>__sync_synchronize (...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005fsynchronize"></a> |
| <p>This built-in function issues a full memory barrier. |
| </p> |
| </dd> |
| <dt><code><var>type</var> __sync_lock_test_and_set (<var>type</var> *ptr, <var>type</var> value, ...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005flock_005ftest_005fand_005fset"></a> |
| <p>This built-in function, as described by Intel, is not a traditional test-and-set |
| operation, but rather an atomic exchange operation. It writes <var>value</var> |
| into <code>*<var>ptr</var></code>, and returns the previous contents of |
| <code>*<var>ptr</var></code>. |
| </p> |
| <p>Many targets have only minimal support for such locks, and do not support |
| a full exchange operation. In this case, a target may support reduced |
| functionality here by which the <em>only</em> valid value to store is the |
| immediate constant 1. The exact value actually stored in <code>*<var>ptr</var></code> |
| is implementation defined. |
| </p> |
| <p>This built-in function is not a full barrier, |
| but rather an <em>acquire barrier</em>. |
| This means that references after the operation cannot move to (or be |
| speculated to) before the operation, but previous memory stores may not |
| be globally visible yet, and previous memory loads may not yet be |
| satisfied. |
| </p> |
| </dd> |
| <dt><code>void __sync_lock_release (<var>type</var> *ptr, ...)</code></dt> |
| <dd><a name="index-_005f_005fsync_005flock_005frelease"></a> |
| <p>This built-in function releases the lock acquired by |
| <code>__sync_lock_test_and_set</code>. |
| Normally this means writing the constant 0 to <code>*<var>ptr</var></code>. |
| </p> |
| <p>This built-in function is not a full barrier, |
| but rather a <em>release barrier</em>. |
| This means that all previous memory stores are globally visible, and all |
| previous memory loads have been satisfied, but following memory reads |
| are not prevented from being speculated to before the barrier. |
| </p></dd> |
| </dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins" accesskey="n" rel="next">__atomic Builtins</a>, Previous: <a href="Offsetof.html#Offsetof" accesskey="p" rel="prev">Offsetof</a>, Up: <a href="C-Extensions.html#C-Extensions" accesskey="u" rel="up">C Extensions</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p> |
| </div> |
| |
| |
| |
| </body> |
| </html> |
