<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
<html>
|
<!-- Copyright (C) 1988-2016 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 <code>__sync</code> 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 normal GCC practice by not using
|
the ‘<samp>__builtin_</samp>’ prefix and also by being overloaded so 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> or their unsigned
|
counterparts. GCC allows any scalar type that is 1, 2, 4 or 8 bytes in
|
size other than the C type <code>_Bool</code> or the C++ type <code>bool</code>.
|
Operations on pointer arguments are performed as if the operands were
|
of the <code>uintptr_t</code> type. That is, they are not scaled by the size
|
of the type to which the pointer points.
|
</p>
|
<p>These functions are implemented in terms of the ‘<samp>__atomic</samp>’
|
builtins (see <a href="_005f_005fatomic-Builtins.html#g_t_005f_005fatomic-Builtins">__atomic Builtins</a>). They should not be used for new
|
code which should use the ‘<samp>__atomic</samp>’ builtins instead.
|
</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 to 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
|
listed variables are protected, or it could mean a list of additional
|
variables to be protected. The list is ignored by GCC which treats it as
|
empty. GCC interprets an empty list as meaning that all globally
|
accessible variables should be protected.
|
</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, operations
|
on integer operands have the following semantics. Operations on pointer
|
arguments are performed as if the operands were of the <code>uintptr_t</code>
|
type. That is, they are not scaled by the size of the type to which
|
the pointer points.
|
</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>The object pointed to by the first argument must be of integer or pointer
|
type. It must not be a Boolean type.
|
</p>
|
<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, operations on integer operands have
|
the following semantics. Operations on pointer operands are performed as
|
if the operand’s type were <code>uintptr_t</code>.
|
</p>
|
<div class="smallexample">
|
<pre class="smallexample">{ *ptr <var>op</var>= value; return *ptr; }
|
{ *ptr = ~(*ptr & value); return *ptr; } // nand
|
</pre></div>
|
|
<p>The same constraints on arguments apply as for the corresponding
|
<code>__sync_op_and_fetch</code> built-in functions.
|
</p>
|
<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>
|
