| <!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): __atomic Builtins</title> |
| |
| <meta name="description" content="Using the GNU Compiler Collection (GCC): __atomic Builtins"> |
| <meta name="keywords" content="Using the GNU Compiler Collection (GCC): __atomic 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="Integer-Overflow-Builtins.html#Integer-Overflow-Builtins" rel="next" title="Integer Overflow Builtins"> |
| <link href="_005f_005fsync-Builtins.html#g_t_005f_005fsync-Builtins" rel="prev" title="__sync Builtins"> |
| <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_005fatomic-Builtins"></a> |
| <div class="header"> |
| <p> |
| Next: <a href="Integer-Overflow-Builtins.html#Integer-Overflow-Builtins" accesskey="n" rel="next">Integer Overflow Builtins</a>, Previous: <a href="_005f_005fsync-Builtins.html#g_t_005f_005fsync-Builtins" accesskey="p" rel="prev">__sync Builtins</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="Built_002din-Functions-for-Memory-Model-Aware-Atomic-Operations"></a> |
| <h3 class="section">6.51 Built-in Functions for Memory Model Aware Atomic Operations</h3> |
| |
| <p>The following built-in functions approximately match the requirements for |
| C++11 memory model. Many are similar to the ‘<samp>__sync</samp>’ prefixed built-in |
| functions, but all also have a memory model parameter. These are all |
| identified by being prefixed with ‘<samp>__atomic</samp>’, and most are overloaded |
| such that they work with multiple types. |
| </p> |
| <p>GCC allows any integral scalar or pointer type that is 1, 2, 4, or 8 |
| bytes in length. 16-byte integral types are also allowed if |
| ‘<samp>__int128</samp>’ (see <a href="_005f_005fint128.html#g_t_005f_005fint128">__int128</a>) is supported by the architecture. |
| </p> |
| <p>Target architectures are encouraged to provide their own patterns for |
| each of these built-in functions. If no target is provided, the original |
| non-memory model set of ‘<samp>__sync</samp>’ atomic built-in functions are |
| utilized, along with any required synchronization fences surrounding it in |
| order to achieve the proper behavior. Execution in this case is subject |
| to the same restrictions as those built-in functions. |
| </p> |
| <p>If there is no pattern or mechanism to provide a lock free instruction |
| sequence, a call is made to an external routine with the same parameters |
| to be resolved at run time. |
| </p> |
| <p>The four non-arithmetic functions (load, store, exchange, and |
| compare_exchange) all have a generic version as well. This generic |
| version works on any data type. If the data type size maps to one |
| of the integral sizes that may have lock free support, the generic |
| version utilizes the lock free built-in function. Otherwise an |
| external call is left to be resolved at run time. This external call is |
| the same format with the addition of a ‘<samp>size_t</samp>’ parameter inserted |
| as the first parameter indicating the size of the object being pointed to. |
| All objects must be the same size. |
| </p> |
| <p>There are 6 different memory models that can be specified. These map |
| to the same names in the C++11 standard. Refer there or to the |
| <a href="http://gcc.gnu.org/wiki/Atomic/GCCMM/AtomicSync">GCC wiki on |
| atomic synchronization</a> for more detailed definitions. These memory |
| models integrate both barriers to code motion as well as synchronization |
| requirements with other threads. These are listed in approximately |
| ascending order of strength. It is also possible to use target specific |
| flags for memory model flags, like Hardware Lock Elision. |
| </p> |
| <dl compact="compact"> |
| <dt><code>__ATOMIC_RELAXED</code></dt> |
| <dd><p>No barriers or synchronization. |
| </p></dd> |
| <dt><code>__ATOMIC_CONSUME</code></dt> |
| <dd><p>Data dependency only for both barrier and synchronization with another |
| thread. |
| </p></dd> |
| <dt><code>__ATOMIC_ACQUIRE</code></dt> |
| <dd><p>Barrier to hoisting of code and synchronizes with release (or stronger) |
| semantic stores from another thread. |
| </p></dd> |
| <dt><code>__ATOMIC_RELEASE</code></dt> |
| <dd><p>Barrier to sinking of code and synchronizes with acquire (or stronger) |
| semantic loads from another thread. |
| </p></dd> |
| <dt><code>__ATOMIC_ACQ_REL</code></dt> |
| <dd><p>Full barrier in both directions and synchronizes with acquire loads and |
| release stores in another thread. |
| </p></dd> |
| <dt><code>__ATOMIC_SEQ_CST</code></dt> |
| <dd><p>Full barrier in both directions and synchronizes with acquire loads and |
| release stores in all threads. |
| </p></dd> |
| </dl> |
| |
| <p>When implementing patterns for these built-in functions, the memory model |
| parameter can be ignored as long as the pattern implements the most |
| restrictive <code>__ATOMIC_SEQ_CST</code> model. Any of the other memory models |
| execute correctly with this memory model but they may not execute as |
| efficiently as they could with a more appropriate implementation of the |
| relaxed requirements. |
| </p> |
| <p>Note that the C++11 standard allows for the memory model parameter to be |
| determined at run time rather than at compile time. These built-in |
| functions map any run-time value to <code>__ATOMIC_SEQ_CST</code> rather |
| than invoke a runtime library call or inline a switch statement. This is |
| standard compliant, safe, and the simplest approach for now. |
| </p> |
| <p>The memory model parameter is a signed int, but only the lower 8 bits are |
| reserved for the memory model. The remainder of the signed int is reserved |
| for future use and should be 0. Use of the predefined atomic values |
| ensures proper usage. |
| </p> |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fload_005fn"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_load_n</strong> <em>(<var>type</var> *ptr, int memmodel)</em></dt> |
| <dd><p>This built-in function implements an atomic load operation. It returns the |
| contents of <code>*<var>ptr</var></code>. |
| </p> |
| <p>The valid memory model variants are |
| <code>__ATOMIC_RELAXED</code>, <code>__ATOMIC_SEQ_CST</code>, <code>__ATOMIC_ACQUIRE</code>, |
| and <code>__ATOMIC_CONSUME</code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fload"></a>Built-in Function: <em>void</em> <strong>__atomic_load</strong> <em>(<var>type</var> *ptr, <var>type</var> *ret, int memmodel)</em></dt> |
| <dd><p>This is the generic version of an atomic load. It returns the |
| contents of <code>*<var>ptr</var></code> in <code>*<var>ret</var></code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fstore_005fn"></a>Built-in Function: <em>void</em> <strong>__atomic_store_n</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dd><p>This built-in function implements an atomic store operation. It writes |
| <code><var>val</var></code> into <code>*<var>ptr</var></code>. |
| </p> |
| <p>The valid memory model variants are |
| <code>__ATOMIC_RELAXED</code>, <code>__ATOMIC_SEQ_CST</code>, and <code>__ATOMIC_RELEASE</code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fstore"></a>Built-in Function: <em>void</em> <strong>__atomic_store</strong> <em>(<var>type</var> *ptr, <var>type</var> *val, int memmodel)</em></dt> |
| <dd><p>This is the generic version of an atomic store. It stores the value |
| of <code>*<var>val</var></code> into <code>*<var>ptr</var></code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fexchange_005fn"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_exchange_n</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dd><p>This built-in function implements an atomic exchange operation. It writes |
| <var>val</var> into <code>*<var>ptr</var></code>, and returns the previous contents of |
| <code>*<var>ptr</var></code>. |
| </p> |
| <p>The valid memory model variants are |
| <code>__ATOMIC_RELAXED</code>, <code>__ATOMIC_SEQ_CST</code>, <code>__ATOMIC_ACQUIRE</code>, |
| <code>__ATOMIC_RELEASE</code>, and <code>__ATOMIC_ACQ_REL</code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fexchange"></a>Built-in Function: <em>void</em> <strong>__atomic_exchange</strong> <em>(<var>type</var> *ptr, <var>type</var> *val, <var>type</var> *ret, int memmodel)</em></dt> |
| <dd><p>This is the generic version of an atomic exchange. It stores the |
| contents of <code>*<var>val</var></code> into <code>*<var>ptr</var></code>. The original value |
| of <code>*<var>ptr</var></code> is copied into <code>*<var>ret</var></code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fcompare_005fexchange_005fn"></a>Built-in Function: <em>bool</em> <strong>__atomic_compare_exchange_n</strong> <em>(<var>type</var> *ptr, <var>type</var> *expected, <var>type</var> desired, bool weak, int success_memmodel, int failure_memmodel)</em></dt> |
| <dd><p>This built-in function implements an atomic compare and exchange operation. |
| This compares the contents of <code>*<var>ptr</var></code> with the contents of |
| <code>*<var>expected</var></code> and if equal, writes <var>desired</var> into |
| <code>*<var>ptr</var></code>. If they are not equal, the current contents of |
| <code>*<var>ptr</var></code> is written into <code>*<var>expected</var></code>. <var>weak</var> is true |
| for weak compare_exchange, and false for the strong variation. Many targets |
| only offer the strong variation and ignore the parameter. When in doubt, use |
| the strong variation. |
| </p> |
| <p>True is returned if <var>desired</var> is written into |
| <code>*<var>ptr</var></code> and the execution is considered to conform to the |
| memory model specified by <var>success_memmodel</var>. There are no |
| restrictions on what memory model can be used here. |
| </p> |
| <p>False is returned otherwise, and the execution is considered to conform |
| to <var>failure_memmodel</var>. This memory model cannot be |
| <code>__ATOMIC_RELEASE</code> nor <code>__ATOMIC_ACQ_REL</code>. It also cannot be a |
| stronger model than that specified by <var>success_memmodel</var>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fcompare_005fexchange"></a>Built-in Function: <em>bool</em> <strong>__atomic_compare_exchange</strong> <em>(<var>type</var> *ptr, <var>type</var> *expected, <var>type</var> *desired, bool weak, int success_memmodel, int failure_memmodel)</em></dt> |
| <dd><p>This built-in function implements the generic version of |
| <code>__atomic_compare_exchange</code>. The function is virtually identical to |
| <code>__atomic_compare_exchange_n</code>, except the desired value is also a |
| pointer. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fadd_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_add_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005fsub_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_sub_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005fand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_and_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005fxor_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_xor_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005for_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_or_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005fnand_005ffetch"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_nand_fetch</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dd><p>These built-in functions perform the operation suggested by the name, and |
| return the result of the operation. That is, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">{ *ptr <var>op</var>= val; return *ptr; } |
| </pre></div> |
| |
| <p>All memory models are valid. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005fadd"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_add</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005fsub"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_sub</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005fand"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_and</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005fxor"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_xor</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005for"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_or</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dt><a name="index-_005f_005fatomic_005ffetch_005fnand"></a>Built-in Function: <em><var>type</var></em> <strong>__atomic_fetch_nand</strong> <em>(<var>type</var> *ptr, <var>type</var> val, int memmodel)</em></dt> |
| <dd><p>These built-in functions perform the operation suggested by the name, and |
| return the value that had previously been in <code>*<var>ptr</var></code>. That is, |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">{ tmp = *ptr; *ptr <var>op</var>= val; return tmp; } |
| </pre></div> |
| |
| <p>All memory models are valid. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005ftest_005fand_005fset"></a>Built-in Function: <em>bool</em> <strong>__atomic_test_and_set</strong> <em>(void *ptr, int memmodel)</em></dt> |
| <dd> |
| <p>This built-in function performs an atomic test-and-set operation on |
| the byte at <code>*<var>ptr</var></code>. The byte is set to some implementation |
| defined nonzero “set” value and the return value is <code>true</code> if and only |
| if the previous contents were “set”. |
| It should be only used for operands of type <code>bool</code> or <code>char</code>. For |
| other types only part of the value may be set. |
| </p> |
| <p>All memory models are valid. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fclear"></a>Built-in Function: <em>void</em> <strong>__atomic_clear</strong> <em>(bool *ptr, int memmodel)</em></dt> |
| <dd> |
| <p>This built-in function performs an atomic clear operation on |
| <code>*<var>ptr</var></code>. After the operation, <code>*<var>ptr</var></code> contains 0. |
| It should be only used for operands of type <code>bool</code> or <code>char</code> and |
| in conjunction with <code>__atomic_test_and_set</code>. |
| For other types it may only clear partially. If the type is not <code>bool</code> |
| prefer using <code>__atomic_store</code>. |
| </p> |
| <p>The valid memory model variants are |
| <code>__ATOMIC_RELAXED</code>, <code>__ATOMIC_SEQ_CST</code>, and |
| <code>__ATOMIC_RELEASE</code>. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fthread_005ffence"></a>Built-in Function: <em>void</em> <strong>__atomic_thread_fence</strong> <em>(int memmodel)</em></dt> |
| <dd> |
| <p>This built-in function acts as a synchronization fence between threads |
| based on the specified memory model. |
| </p> |
| <p>All memory orders are valid. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fsignal_005ffence"></a>Built-in Function: <em>void</em> <strong>__atomic_signal_fence</strong> <em>(int memmodel)</em></dt> |
| <dd> |
| <p>This built-in function acts as a synchronization fence between a thread |
| and signal handlers based in the same thread. |
| </p> |
| <p>All memory orders are valid. |
| </p> |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005falways_005flock_005ffree"></a>Built-in Function: <em>bool</em> <strong>__atomic_always_lock_free</strong> <em>(size_t size, void *ptr)</em></dt> |
| <dd> |
| <p>This built-in function returns true if objects of <var>size</var> bytes always |
| generate lock free atomic instructions for the target architecture. |
| <var>size</var> must resolve to a compile-time constant and the result also |
| resolves to a compile-time constant. |
| </p> |
| <p><var>ptr</var> is an optional pointer to the object that may be used to determine |
| alignment. A value of 0 indicates typical alignment should be used. The |
| compiler may also ignore this parameter. |
| </p> |
| <div class="smallexample"> |
| <pre class="smallexample">if (_atomic_always_lock_free (sizeof (long long), 0)) |
| </pre></div> |
| |
| </dd></dl> |
| |
| <dl> |
| <dt><a name="index-_005f_005fatomic_005fis_005flock_005ffree"></a>Built-in Function: <em>bool</em> <strong>__atomic_is_lock_free</strong> <em>(size_t size, void *ptr)</em></dt> |
| <dd> |
| <p>This built-in function returns true if objects of <var>size</var> bytes always |
| generate lock free atomic instructions for the target architecture. If |
| it is not known to be lock free a call is made to a runtime routine named |
| <code>__atomic_is_lock_free</code>. |
| </p> |
| <p><var>ptr</var> is an optional pointer to the object that may be used to determine |
| alignment. A value of 0 indicates typical alignment should be used. The |
| compiler may also ignore this parameter. |
| </p></dd></dl> |
| |
| <hr> |
| <div class="header"> |
| <p> |
| Next: <a href="Integer-Overflow-Builtins.html#Integer-Overflow-Builtins" accesskey="n" rel="next">Integer Overflow Builtins</a>, Previous: <a href="_005f_005fsync-Builtins.html#g_t_005f_005fsync-Builtins" accesskey="p" rel="prev">__sync Builtins</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> |