1<html lang="en"> 2<head> 3<title>Atomic Builtins - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="C-Extensions.html#C-Extensions" title="C Extensions"> 9<link rel="prev" href="Offsetof.html#Offsetof" title="Offsetof"> 10<link rel="next" href="Object-Size-Checking.html#Object-Size-Checking" title="Object Size Checking"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Atomic-Builtins"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Object-Size-Checking.html#Object-Size-Checking">Object Size Checking</a>, 53Previous: <a rel="previous" accesskey="p" href="Offsetof.html#Offsetof">Offsetof</a>, 54Up: <a rel="up" accesskey="u" href="C-Extensions.html#C-Extensions">C Extensions</a> 55<hr> 56</div> 57 58<h3 class="section">6.51 Built-in functions for atomic memory access</h3> 59 60<p>The following builtins are intended to be compatible with those described 61in the <cite>Intel Itanium Processor-specific Application Binary Interface</cite>, 62section 7.4. As such, they depart from the normal GCC practice of using 63the “__builtin_” prefix, and further that they are overloaded such that 64they work on multiple types. 65 66 <p>The definition given in the Intel documentation allows only for the use of 67the types <code>int</code>, <code>long</code>, <code>long long</code> as well as their unsigned 68counterparts. GCC will allow any integral scalar or pointer type that is 691, 2, 4 or 8 bytes in length. 70 71 <p>Not all operations are supported by all target processors. If a particular 72operation cannot be implemented on the target processor, a warning will be 73generated and a call an external function will be generated. The external 74function will carry the same name as the builtin, with an additional suffix 75‘<samp><span class="samp">_</span><var>n</var></samp>’ where <var>n</var> is the size of the data type. 76 77<!-- ??? Should we have a mechanism to suppress this warning? This is almost --> 78<!-- useful for implementing the operation under the control of an external --> 79<!-- mutex. --> 80 <p>In most cases, these builtins are considered a <dfn>full barrier</dfn>. That is, 81no memory operand will be moved across the operation, either forward or 82backward. Further, instructions will be issued as necessary to prevent the 83processor from speculating loads across the operation and from queuing stores 84after the operation. 85 86 <p>All of the routines are described in the Intel documentation to take 87“an optional list of variables protected by the memory barrier”. It's 88not clear what is meant by that; it could mean that <em>only</em> the 89following variables are protected, or it could mean that these variables 90should in addition be protected. At present GCC ignores this list and 91protects all variables which are globally accessible. If in the future 92we make some use of this list, an empty list will continue to mean all 93globally accessible variables. 94 95 <dl> 96<dt><var>type</var><code> __sync_fetch_and_add (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_fetch_and_sub (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_fetch_and_or (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_fetch_and_and (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_fetch_and_xor (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_fetch_and_nand (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dd><a name="index-g_t_005f_005fsync_005ffetch_005fand_005fadd-2707"></a><a name="index-g_t_005f_005fsync_005ffetch_005fand_005fsub-2708"></a><a name="index-g_t_005f_005fsync_005ffetch_005fand_005for-2709"></a><a name="index-g_t_005f_005fsync_005ffetch_005fand_005fand-2710"></a><a name="index-g_t_005f_005fsync_005ffetch_005fand_005fxor-2711"></a><a name="index-g_t_005f_005fsync_005ffetch_005fand_005fnand-2712"></a>These builtins perform the operation suggested by the name, and 97returns the value that had previously been in memory. That is, 98 99 <pre class="smallexample"> { tmp = *ptr; *ptr <var>op</var>= value; return tmp; } 100 { tmp = *ptr; *ptr = ~(tmp & value); return tmp; } // nand 101</pre> 102 <p><em>Note:</em> GCC 4.4 and later implement <code>__sync_fetch_and_nand</code> 103builtin as <code>*ptr = ~(tmp & value)</code> instead of <code>*ptr = ~tmp & value</code>. 104 105 <br><dt><var>type</var><code> __sync_add_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_sub_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_or_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_and_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_xor_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dt><var>type</var><code> __sync_nand_and_fetch (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dd><a name="index-g_t_005f_005fsync_005fadd_005fand_005ffetch-2713"></a><a name="index-g_t_005f_005fsync_005fsub_005fand_005ffetch-2714"></a><a name="index-g_t_005f_005fsync_005for_005fand_005ffetch-2715"></a><a name="index-g_t_005f_005fsync_005fand_005fand_005ffetch-2716"></a><a name="index-g_t_005f_005fsync_005fxor_005fand_005ffetch-2717"></a><a name="index-g_t_005f_005fsync_005fnand_005fand_005ffetch-2718"></a>These builtins perform the operation suggested by the name, and 106return the new value. That is, 107 108 <pre class="smallexample"> { *ptr <var>op</var>= value; return *ptr; } 109 { *ptr = ~(*ptr & value); return *ptr; } // nand 110</pre> 111 <p><em>Note:</em> GCC 4.4 and later implement <code>__sync_nand_and_fetch</code> 112builtin as <code>*ptr = ~(*ptr & value)</code> instead of 113<code>*ptr = ~*ptr & value</code>. 114 115 <br><dt><code>bool __sync_bool_compare_and_swap (</code><var>type</var><code> *ptr, </code><var>type</var><code> oldval </code><var>type</var><code> newval, ...)</code><dt><var>type</var><code> __sync_val_compare_and_swap (</code><var>type</var><code> *ptr, </code><var>type</var><code> oldval </code><var>type</var><code> newval, ...)</code><dd><a name="index-g_t_005f_005fsync_005fbool_005fcompare_005fand_005fswap-2719"></a><a name="index-g_t_005f_005fsync_005fval_005fcompare_005fand_005fswap-2720"></a>These builtins perform an atomic compare and swap. That is, if the current 116value of <code>*</code><var>ptr</var> is <var>oldval</var>, then write <var>newval</var> into 117<code>*</code><var>ptr</var>. 118 119 <p>The “bool” version returns true if the comparison is successful and 120<var>newval</var> was written. The “val” version returns the contents 121of <code>*</code><var>ptr</var> before the operation. 122 123 <br><dt><code>__sync_synchronize (...)</code><dd><a name="index-g_t_005f_005fsync_005fsynchronize-2721"></a>This builtin issues a full memory barrier. 124 125 <br><dt><var>type</var><code> __sync_lock_test_and_set (</code><var>type</var><code> *ptr, </code><var>type</var><code> value, ...)</code><dd><a name="index-g_t_005f_005fsync_005flock_005ftest_005fand_005fset-2722"></a>This builtin, as described by Intel, is not a traditional test-and-set 126operation, but rather an atomic exchange operation. It writes <var>value</var> 127into <code>*</code><var>ptr</var>, and returns the previous contents of 128<code>*</code><var>ptr</var>. 129 130 <p>Many targets have only minimal support for such locks, and do not support 131a full exchange operation. In this case, a target may support reduced 132functionality here by which the <em>only</em> valid value to store is the 133immediate constant 1. The exact value actually stored in <code>*</code><var>ptr</var> 134is implementation defined. 135 136 <p>This builtin is not a full barrier, but rather an <dfn>acquire barrier</dfn>. 137This means that references after the builtin cannot move to (or be 138speculated to) before the builtin, but previous memory stores may not 139be globally visible yet, and previous memory loads may not yet be 140satisfied. 141 142 <br><dt><code>void __sync_lock_release (</code><var>type</var><code> *ptr, ...)</code><dd><a name="index-g_t_005f_005fsync_005flock_005frelease-2723"></a>This builtin releases the lock acquired by <code>__sync_lock_test_and_set</code>. 143Normally this means writing the constant 0 to <code>*</code><var>ptr</var>. 144 145 <p>This builtin is not a full barrier, but rather a <dfn>release barrier</dfn>. 146This means that all previous memory stores are globally visible, and all 147previous memory loads have been satisfied, but following memory reads 148are not prevented from being speculated to before the barrier. 149</dl> 150 151 </body></html> 152 153