mirror/rtic
1
0
Fork 0
mirror of https://github.com/rtic-rs/rtic.git synced 2024-12-26 11:59:33 +01:00
Code Issues Projects Releases Packages Wiki Activity
rtic/2/api/portable_atomic/struct.AtomicPtr.html

462 lines
92 KiB
HTML
Raw Normal View History

deploy: d251ba717393a73e9ea26a34fe738e3baec477d2
2024-10-24 07:57:30 +02:00
<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><meta name="generator" content="rustdoc"><meta name="description" content="A raw pointer type which can be safely shared between threads."><title>AtomicPtr in portable_atomic - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-46f98efaafac5295.ttf.woff2,FiraSans-Regular-018c141bf0843ffd.woff2,FiraSans-Medium-8f9a781e4970d388.woff2,SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2,SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-76eba96aa4d2e634.css"><link rel="stylesheet" href="../static.files/rustdoc-492a78a4a87dcc01.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="portable_atomic" data-themes="" data-resource-suffix="" data-rustdoc-version="1.82.0 (f6e511eec 2024-10-15)" data-channel="1.82.0" data-search-js="search-a99f1315e7cc5121.js" data-settings-js="settings-4313503d2e1961c2.js" ><script src="../static.files/storage-118b08c4c78b968e.js"></script><script defer src="sidebar-items.js"></script><script defer src="../static.files/main-921df33f47b8780c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-3b12f09e550e0385.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-422f7d1d52889060.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-2c020d218678b618.svg"></head><body class="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../portable_atomic/index.html">portable_<wbr>atomic</a><span class="version">1.9.0</span></h2></div><h2 class="location"><a href="#">Atomic<wbr>Ptr</a></h2><div class="sidebar-elems"><section><h3><a href="#implementations">Methods</a></h3><ul class="block method"><li><a href="#method.as_ptr">as_ptr</a></li><li><a href="#method.bit_clear">bit_clear</a></li><li><a href="#method.bit_set">bit_set</a></li><li><a href="#method.bit_toggle">bit_toggle</a></li><li><a href="#method.compare_exchange">compare_exchange</a></li><li><a href="#method.compare_exchange_weak">compare_exchange_weak</a></li><li><a href="#method.fetch_and">fetch_and</a></li><li><a href="#method.fetch_byte_add">fetch_byte_add</a></li><li><a href="#method.fetch_byte_sub">fetch_byte_sub</a></li><li><a href="#method.fetch_or">fetch_or</a></li><li><a href="#method.fetch_ptr_add">fetch_ptr_add</a></li><li><a href="#method.fetch_ptr_sub">fetch_ptr_sub</a></li><li><a href="#method.fetch_update">fetch_update</a></li><li><a href="#method.fetch_xor">fetch_xor</a></li><li><a href="#method.from_ptr">from_ptr</a></li><li><a href="#method.get_mut">get_mut</a></li><li><a href="#method.into_inner">into_inner</a></li><li><a href="#method.is_always_lock_free">is_always_lock_free</a></li><li><a href="#method.is_lock_free">is_lock_free</a></li><li><a href="#method.load">load</a></li><li><a href="#method.new">new</a></li><li><a href="#method.store">store</a></li><li><a href="#method.swap">swap</a></li></ul><h3><a href="#trait-implementations">Trait Implementations</a></h3><ul class="block trait-implementation"><li><a href="#impl-Debug-for-AtomicPtr%3CT%3E">Debug</a></li><li><a href="#impl-Default-for-AtomicPtr%3CT%3E">Default</a></li><li><a href="#impl-From%3C*mut+T%3E-for-AtomicPtr%3CT%3E">From&#60;*mut T&#62;</a></li><li><a href="#impl-Pointer-for-AtomicPtr%3CT%3E">Pointer</a></li><li><a href="#impl-RefUnwindSafe-for-AtomicPtr%3CT%3E">RefUnwindSafe</a></li></ul><h3><a href="#synthetic-implementations">Auto Trait Implementations</a></h3><ul class="block synthetic-implem
<p>This type has the same in-memory representation as a <code>*mut T</code>.</p>
<p>If the compiler and the platform support atomic loads and stores of pointers,
this type is a wrapper for the standard library’s
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/struct.AtomicPtr.html" title="struct core::sync::atomic::AtomicPtr"><code>AtomicPtr</code></a>. If the platform supports it
but the compiler does not, atomic operations are implemented using inline
assembly.</p>
</div></details><h2 id="implementations" class="section-header">Implementations<a href="#implementations" class="anchor">§</a></h2><div id="implementations-list"><details class="toggle implementors-toggle" open><summary><section id="impl-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1577-2509">source</a><a href="#impl-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.new" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1590-1593">source</a><h4 class="code-header">pub const fn <a href="#method.new" class="fn">new</a>(p: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>) -&gt; Self</h4></section></summary><div class="docblock"><p>Creates a new <code>AtomicPtr</code>.</p>
<h5 id="examples"><a class="doc-anchor" href="#examples">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::AtomicPtr;
<span class="kw">let </span>ptr = <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>atomic_ptr = AtomicPtr::new(ptr);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.from_ptr" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1623-1627">source</a><h4 class="code-header">pub unsafe fn <a href="#method.from_ptr" class="fn">from_ptr</a>&lt;'a&gt;(ptr: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut </a><a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>) -&gt; &amp;'a Self</h4></section></summary><div class="docblock"><p>Creates a new <code>AtomicPtr</code> from a pointer.</p>
<h5 id="safety"><a class="doc-anchor" href="#safety">§</a>Safety</h5>
<ul>
<li><code>ptr</code> must be aligned to <code>align_of::&lt;AtomicPtr&lt;T&gt;&gt;()</code> (note that on some platforms this
can be bigger than <code>align_of::&lt;*mut T&gt;()</code>).</li>
<li><code>ptr</code> must be <a href="https://doc.rust-lang.org/1.82.0/core/ptr/index.html#safety" title="mod core::ptr">valid</a> for both reads and writes for the whole lifetime <code>'a</code>.</li>
<li>If this atomic type is <a href="struct.AtomicPtr.html#method.is_lock_free" title="associated function portable_atomic::AtomicPtr::is_lock_free">lock-free</a>, non-atomic accesses to the value
behind <code>ptr</code> must have a happens-before relationship with atomic accesses via the returned
value (or vice-versa).
<ul>
<li>In other words, time periods where the value is accessed atomically may not overlap
with periods where the value is accessed non-atomically.</li>
<li>This requirement is trivially satisfied if <code>ptr</code> is never used non-atomically for the
duration of lifetime <code>'a</code>. Most use cases should be able to follow this guideline.</li>
<li>This requirement is also trivially satisfied if all accesses (atomic or not) are done
from the same thread.</li>
</ul>
</li>
<li>If this atomic type is <em>not</em> lock-free:
<ul>
<li>Any accesses to the value behind <code>ptr</code> must have a happens-before relationship
with accesses via the returned value (or vice-versa).</li>
<li>Any concurrent accesses to the value behind <code>ptr</code> for the duration of lifetime <code>'a</code> must
be compatible with operations performed by this atomic type.</li>
</ul>
</li>
<li>This method must not be used to create overlapping or mixed-size atomic accesses, as
these are not supported by the memory model.</li>
</ul>
</div></details><details class="toggle method-toggle" open><summary><section id="method.is_lock_free" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1644-1646">source</a><h4 class="code-header">pub fn <a href="#method.is_lock_free" class="fn">is_lock_free</a>() -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Returns <code>true</code> if operations on values of this type are lock-free.</p>
<p>If the compiler or the platform doesn’t support the necessary
atomic instructions, global locks for every potentially
concurrent atomic operation will be used.</p>
<h5 id="examples-1"><a class="doc-anchor" href="#examples-1">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::AtomicPtr;
<span class="kw">let </span>is_lock_free = AtomicPtr::&lt;()&gt;::is_lock_free();</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.is_always_lock_free" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1666-1668">source</a><h4 class="code-header">pub const fn <a href="#method.is_always_lock_free" class="fn">is_always_lock_free</a>() -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Returns <code>true</code> if operations on values of this type are lock-free.</p>
<p>If the compiler or the platform doesn’t support the necessary
atomic instructions, global locks for every potentially
concurrent atomic operation will be used.</p>
<p><strong>Note:</strong> If the atomic operation relies on dynamic CPU feature detection,
this type may be lock-free even if the function returns false.</p>
<h5 id="examples-2"><a class="doc-anchor" href="#examples-2">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::AtomicPtr;
<span class="kw">const </span>IS_ALWAYS_LOCK_FREE: bool = AtomicPtr::&lt;()&gt;::is_always_lock_free();</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.get_mut" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1689-1691">source</a><h4 class="code-header">pub fn <a href="#method.get_mut" class="fn">get_mut</a>(&amp;mut self) -&gt; &amp;mut <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Returns a mutable reference to the underlying pointer.</p>
<p>This is safe because the mutable reference guarantees that no other threads are
concurrently accessing the atomic data.</p>
<h5 id="examples-3"><a class="doc-anchor" href="#examples-3">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span><span class="kw-2">mut </span>data = <span class="number">10</span>;
<span class="kw">let </span><span class="kw-2">mut </span>atomic_ptr = AtomicPtr::new(<span class="kw-2">&amp;mut </span>data);
<span class="kw">let </span><span class="kw-2">mut </span>other_data = <span class="number">5</span>;
<span class="kw-2">*</span>atomic_ptr.get_mut() = <span class="kw-2">&amp;mut </span>other_data;
<span class="macro">assert_eq!</span>(<span class="kw">unsafe </span>{ <span class="kw-2">*</span>atomic_ptr.load(Ordering::SeqCst) }, <span class="number">5</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.into_inner" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1696-1721">source</a><h4 class="code-header">pub const fn <a href="#method.into_inner" class="fn">into_inner</a>(self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Consumes the atomic and returns the contained value.</p>
<p>This is safe because passing <code>self</code> by value guarantees that no other threads are
concurrently accessing the atomic data.</p>
<p>This is <code>const fn</code> on Rust 1.56+.</p>
<h5 id="examples-4"><a class="doc-anchor" href="#examples-4">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::AtomicPtr;
<span class="kw">let </span><span class="kw-2">mut </span>data = <span class="number">5</span>;
<span class="kw">let </span>atomic_ptr = AtomicPtr::new(<span class="kw-2">&amp;mut </span>data);
<span class="macro">assert_eq!</span>(<span class="kw">unsafe </span>{ <span class="kw-2">*</span>atomic_ptr.into_inner() }, <span class="number">5</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.load" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1747-1749">source</a><h4 class="code-header">pub fn <a href="#method.load" class="fn">load</a>(&amp;self, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Loads a value from the pointer.</p>
<p><code>load</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. Possible values are <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.SeqCst" title="variant core::sync::atomic::Ordering::SeqCst"><code>SeqCst</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> and <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="panics"><a class="doc-anchor" href="#panics">§</a>Panics</h5>
<p>Panics if <code>order</code> is <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> or <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.AcqRel" title="variant core::sync::atomic::Ordering::AcqRel"><code>AcqRel</code></a>.</p>
<h5 id="examples-5"><a class="doc-anchor" href="#examples-5">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>ptr = <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>some_ptr = AtomicPtr::new(ptr);
<span class="kw">let </span>value = some_ptr.load(Ordering::Relaxed);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.store" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1777-1779">source</a><h4 class="code-header">pub fn <a href="#method.store" class="fn">store</a>(&amp;self, ptr: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>)</h4></section></summary><div class="docblock"><p>Stores a value into the pointer.</p>
<p><code>store</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. Possible values are <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.SeqCst" title="variant core::sync::atomic::Ordering::SeqCst"><code>SeqCst</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> and <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="panics-1"><a class="doc-anchor" href="#panics-1">§</a>Panics</h5>
<p>Panics if <code>order</code> is <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> or <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.AcqRel" title="variant core::sync::atomic::Ordering::AcqRel"><code>AcqRel</code></a>.</p>
<h5 id="examples-6"><a class="doc-anchor" href="#examples-6">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>ptr = <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>some_ptr = AtomicPtr::new(ptr);
<span class="kw">let </span>other_ptr = <span class="kw-2">&amp;mut </span><span class="number">10</span>;
some_ptr.store(other_ptr, Ordering::Relaxed);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.swap" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1803-1805">source</a><h4 class="code-header">pub fn <a href="#method.swap" class="fn">swap</a>(&amp;self, ptr: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Stores a value into the pointer, returning the previous value.</p>
<p><code>swap</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. All ordering modes are possible. Note that using
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="examples-7"><a class="doc-anchor" href="#examples-7">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>ptr = <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>some_ptr = AtomicPtr::new(ptr);
<span class="kw">let </span>other_ptr = <span class="kw-2">&amp;mut </span><span class="number">10</span>;
<span class="kw">let </span>value = some_ptr.swap(other_ptr, Ordering::Relaxed);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.compare_exchange" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1843-1851">source</a><h4 class="code-header">pub fn <a href="#method.compare_exchange" class="fn">compare_exchange</a>(
&amp;self,
current: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>,
new: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>,
success: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
failure: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>, <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>&gt;</h4></section></summary><div class="docblock"><p>Stores a value into the pointer if the current value is the same as the <code>current</code> value.</p>
<p>The return value is a result indicating whether the new value was written and containing
the previous value. On success this value is guaranteed to be equal to <code>current</code>.</p>
<p><code>compare_exchange</code> takes two <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> arguments to describe the memory
ordering of this operation. <code>success</code> describes the required ordering for the
read-modify-write operation that takes place if the comparison with <code>current</code> succeeds.
<code>failure</code> describes the required ordering for the load operation that takes place when
the comparison fails. Using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> as success ordering makes the store part
of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the successful load
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>. The failure ordering can only be <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.SeqCst" title="variant core::sync::atomic::Ordering::SeqCst"><code>SeqCst</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> or <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="panics-2"><a class="doc-anchor" href="#panics-2">§</a>Panics</h5>
<p>Panics if <code>failure</code> is <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.AcqRel" title="variant core::sync::atomic::Ordering::AcqRel"><code>AcqRel</code></a>.</p>
<h5 id="examples-8"><a class="doc-anchor" href="#examples-8">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>ptr = <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>some_ptr = AtomicPtr::new(ptr);
<span class="kw">let </span>other_ptr = <span class="kw-2">&amp;mut </span><span class="number">10</span>;
<span class="kw">let </span>value = some_ptr.compare_exchange(ptr, other_ptr, Ordering::SeqCst, Ordering::Relaxed);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.compare_exchange_weak" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1894-1902">source</a><h4 class="code-header">pub fn <a href="#method.compare_exchange_weak" class="fn">compare_exchange_weak</a>(
&amp;self,
current: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>,
new: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>,
success: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
failure: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>, <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>&gt;</h4></section></summary><div class="docblock"><p>Stores a value into the pointer if the current value is the same as the <code>current</code> value.</p>
<p>Unlike <a href="struct.AtomicPtr.html#method.compare_exchange" title="method portable_atomic::AtomicPtr::compare_exchange"><code>AtomicPtr::compare_exchange</code></a>, this function is allowed to spuriously fail even when the
comparison succeeds, which can result in more efficient code on some platforms. The
return value is a result indicating whether the new value was written and containing the
previous value.</p>
<p><code>compare_exchange_weak</code> takes two <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> arguments to describe the memory
ordering of this operation. <code>success</code> describes the required ordering for the
read-modify-write operation that takes place if the comparison with <code>current</code> succeeds.
<code>failure</code> describes the required ordering for the load operation that takes place when
the comparison fails. Using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> as success ordering makes the store part
of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the successful load
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>. The failure ordering can only be <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.SeqCst" title="variant core::sync::atomic::Ordering::SeqCst"><code>SeqCst</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> or <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="panics-3"><a class="doc-anchor" href="#panics-3">§</a>Panics</h5>
<p>Panics if <code>failure</code> is <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.AcqRel" title="variant core::sync::atomic::Ordering::AcqRel"><code>AcqRel</code></a>.</p>
<h5 id="examples-9"><a class="doc-anchor" href="#examples-9">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>some_ptr = AtomicPtr::new(<span class="kw-2">&amp;mut </span><span class="number">5</span>);
<span class="kw">let </span>new = <span class="kw-2">&amp;mut </span><span class="number">10</span>;
<span class="kw">let </span><span class="kw-2">mut </span>old = some_ptr.load(Ordering::Relaxed);
<span class="kw">loop </span>{
<span class="kw">match </span>some_ptr.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
<span class="prelude-val">Ok</span>(<span class="kw">_</span>) =&gt; <span class="kw">break</span>,
<span class="prelude-val">Err</span>(x) =&gt; old = x,
}
}</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_update" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1962-1979">source</a><h4 class="code-header">pub fn <a href="#method.fetch_update" class="fn">fetch_update</a>&lt;F&gt;(
&amp;self,
set_order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
fetch_order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>,
f: F,
) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>, <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>&gt;<div class="where">where
F: <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/ops/function/trait.FnMut.html" title="trait core::ops::function::FnMut">FnMut</a>(<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/option/enum.Option.html" title="enum core::option::Option">Option</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>&gt;,</div></h4></section></summary><div class="docblock"><p>Fetches the value, and applies a function to it that returns an optional
new value. Returns a <code>Result</code> of <code>Ok(previous_value)</code> if the function
returned <code>Some(_)</code>, else <code>Err(previous_value)</code>.</p>
<p>Note: This may call the function multiple times if the value has been
changed from other threads in the meantime, as long as the function
returns <code>Some(_)</code>, but the function will have been applied only once to
the stored value.</p>
<p><code>fetch_update</code> takes two <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> arguments to describe the memory
ordering of this operation. The first describes the required ordering for
when the operation finally succeeds while the second describes the
required ordering for loads. These correspond to the success and failure
orderings of <a href="struct.AtomicPtr.html#method.compare_exchange" title="method portable_atomic::AtomicPtr::compare_exchange"><code>compare_exchange</code></a> respectively.</p>
<p>Using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> as success ordering makes the store part of this
operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the final successful
load <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>. The (failed) load ordering can only be <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.SeqCst" title="variant core::sync::atomic::Ordering::SeqCst"><code>SeqCst</code></a>,
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> or <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="panics-4"><a class="doc-anchor" href="#panics-4">§</a>Panics</h5>
<p>Panics if <code>fetch_order</code> is <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a>, <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.AcqRel" title="variant core::sync::atomic::Ordering::AcqRel"><code>AcqRel</code></a>.</p>
<h5 id="considerations"><a class="doc-anchor" href="#considerations">§</a>Considerations</h5>
<p>This method is not magic; it is not provided by the hardware.
It is implemented in terms of <a href="struct.AtomicPtr.html#method.compare_exchange_weak" title="method portable_atomic::AtomicPtr::compare_exchange_weak"><code>compare_exchange_weak</code></a>,
and suffers from the same drawbacks.
In particular, this method will not circumvent the <a href="https://en.wikipedia.org/wiki/ABA_problem">ABA Problem</a>.</p>
<h5 id="examples-10"><a class="doc-anchor" href="#examples-10">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>ptr: <span class="kw-2">*mut </span><span class="kw">_ </span>= <span class="kw-2">&amp;mut </span><span class="number">5</span>;
<span class="kw">let </span>some_ptr = AtomicPtr::new(ptr);
<span class="kw">let </span>new: <span class="kw-2">*mut </span><span class="kw">_ </span>= <span class="kw-2">&amp;mut </span><span class="number">10</span>;
<span class="macro">assert_eq!</span>(some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |<span class="kw">_</span>| <span class="prelude-val">None</span>), <span class="prelude-val">Err</span>(ptr));
<span class="kw">let </span>result = some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| {
<span class="kw">if </span>x == ptr {
<span class="prelude-val">Some</span>(new)
} <span class="kw">else </span>{
<span class="prelude-val">None
</span>}
});
<span class="macro">assert_eq!</span>(result, <span class="prelude-val">Ok</span>(ptr));
<span class="macro">assert_eq!</span>(some_ptr.load(Ordering::SeqCst), new);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_ptr_add" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2034-2036">source</a><h4 class="code-header">pub fn <a href="#method.fetch_ptr_add" class="fn">fetch_ptr_add</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Offsets the pointer’s address by adding <code>val</code> (in units of <code>T</code>),
returning the previous pointer.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_add"><code>wrapping_add</code></a> to atomically perform the
equivalent of <code>ptr = ptr.wrapping_add(val);</code>.</p>
<p>This method operates in units of <code>T</code>, which means that it cannot be used
to offset the pointer by an amount which is not a multiple of
<code>size_of::&lt;T&gt;()</code>. This can sometimes be inconvenient, as you may want to
work with a deliberately misaligned pointer. In such cases, you may use
the <a href="struct.AtomicPtr.html#method.fetch_byte_add" title="method portable_atomic::AtomicPtr::fetch_byte_add"><code>fetch_byte_add</code></a> method instead.</p>
<p><code>fetch_ptr_add</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the
memory ordering of this operation. All ordering modes are possible. Note
that using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="examples-11"><a class="doc-anchor" href="#examples-11">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(core::ptr::null_mut());
<span class="macro">assert_eq!</span>(atom.fetch_ptr_add(<span class="number">1</span>, Ordering::Relaxed).addr(), <span class="number">0</span>);
<span class="comment">// Note: units of `size_of::&lt;i64&gt;()`.
</span><span class="macro">assert_eq!</span>(atom.load(Ordering::Relaxed).addr(), <span class="number">8</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_ptr_sub" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2070-2072">source</a><h4 class="code-header">pub fn <a href="#method.fetch_ptr_sub" class="fn">fetch_ptr_sub</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Offsets the pointer’s address by subtracting <code>val</code> (in units of <code>T</code>),
returning the previous pointer.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_sub"><code>wrapping_sub</code></a> to atomically perform the
equivalent of <code>ptr = ptr.wrapping_sub(val);</code>.</p>
<p>This method operates in units of <code>T</code>, which means that it cannot be used
to offset the pointer by an amount which is not a multiple of
<code>size_of::&lt;T&gt;()</code>. This can sometimes be inconvenient, as you may want to
work with a deliberately misaligned pointer. In such cases, you may use
the <a href="struct.AtomicPtr.html#method.fetch_byte_sub" title="method portable_atomic::AtomicPtr::fetch_byte_sub"><code>fetch_byte_sub</code></a> method instead.</p>
<p><code>fetch_ptr_sub</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory
ordering of this operation. All ordering modes are possible. Note that
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>,
and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="examples-12"><a class="doc-anchor" href="#examples-12">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">let </span>array = [<span class="number">1i32</span>, <span class="number">2i32</span>];
<span class="kw">let </span>atom = AtomicPtr::new(array.as_ptr().wrapping_add(<span class="number">1</span>) <span class="kw">as </span><span class="kw-2">*mut </span><span class="kw">_</span>);
<span class="macro">assert!</span>(core::ptr::eq(atom.fetch_ptr_sub(<span class="number">1</span>, Ordering::Relaxed), <span class="kw-2">&amp;</span>array[<span class="number">1</span>]));
<span class="macro">assert!</span>(core::ptr::eq(atom.load(Ordering::Relaxed), <span class="kw-2">&amp;</span>array[<span class="number">0</span>]));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_byte_add" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2102-2117">source</a><h4 class="code-header">pub fn <a href="#method.fetch_byte_add" class="fn">fetch_byte_add</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Offsets the pointer’s address by adding <code>val</code> <em>bytes</em>, returning the
previous pointer.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_add"><code>wrapping_add</code></a> and <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.cast"><code>cast</code></a> to atomically
perform <code>ptr = ptr.cast::&lt;u8&gt;().wrapping_add(val).cast::&lt;T&gt;()</code>.</p>
<p><code>fetch_byte_add</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the
memory ordering of this operation. All ordering modes are possible. Note
that using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="examples-13"><a class="doc-anchor" href="#examples-13">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(core::ptr::null_mut());
<span class="macro">assert_eq!</span>(atom.fetch_byte_add(<span class="number">1</span>, Ordering::Relaxed).addr(), <span class="number">0</span>);
<span class="comment">// Note: in units of bytes, not `size_of::&lt;i64&gt;()`.
</span><span class="macro">assert_eq!</span>(atom.load(Ordering::Relaxed).addr(), <span class="number">1</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_byte_sub" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2146-2161">source</a><h4 class="code-header">pub fn <a href="#method.fetch_byte_sub" class="fn">fetch_byte_sub</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Offsets the pointer’s address by subtracting <code>val</code> <em>bytes</em>, returning the
previous pointer.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.wrapping_sub"><code>wrapping_sub</code></a> and <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.cast"><code>cast</code></a> to atomically
perform <code>ptr = ptr.cast::&lt;u8&gt;().wrapping_sub(val).cast::&lt;T&gt;()</code>.</p>
<p><code>fetch_byte_sub</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the
memory ordering of this operation. All ordering modes are possible. Note
that using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<h5 id="examples-14"><a class="doc-anchor" href="#examples-14">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(sptr::invalid_mut(<span class="number">1</span>));
<span class="macro">assert_eq!</span>(atom.fetch_byte_sub(<span class="number">1</span>, Ordering::Relaxed).addr(), <span class="number">1</span>);
<span class="macro">assert_eq!</span>(atom.load(Ordering::Relaxed).addr(), <span class="number">0</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_or" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2205-2220">source</a><h4 class="code-header">pub fn <a href="#method.fetch_or" class="fn">fetch_or</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Performs a bitwise “or” operation on the address of the current pointer,
and the argument <code>val</code>, and stores a pointer with provenance of the
current pointer and the resulting address.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a> to atomically perform
<code>ptr = ptr.map_addr(|a| a | val)</code>. This can be used in tagged
pointer schemes to atomically set tag bits.</p>
<p><strong>Caveat</strong>: This operation returns the previous value. To compute the
stored value without losing provenance, you may use <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a>. For
example: <code>a.fetch_or(val).map_addr(|a| a | val)</code>.</p>
<p><code>fetch_or</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory
ordering of this operation. All ordering modes are possible. Note that
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>,
and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This API and its claimed semantics are part of the Strict Provenance
experiment, see the <a href="https://doc.rust-lang.org/1.82.0/core/ptr/index.html" title="mod core::ptr">module documentation for <code>ptr</code></a> for
details.</p>
<h5 id="examples-15"><a class="doc-anchor" href="#examples-15">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer);
<span class="comment">// Tag the bottom bit of the pointer.
</span><span class="macro">assert_eq!</span>(atom.fetch_or(<span class="number">1</span>, Ordering::Relaxed).addr() &amp; <span class="number">1</span>, <span class="number">0</span>);
<span class="comment">// Extract and untag.
</span><span class="kw">let </span>tagged = atom.load(Ordering::Relaxed);
<span class="macro">assert_eq!</span>(tagged.addr() &amp; <span class="number">1</span>, <span class="number">1</span>);
<span class="macro">assert_eq!</span>(tagged.map_addr(|p| p &amp; !<span class="number">1</span>), pointer);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_and" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2262-2277">source</a><h4 class="code-header">pub fn <a href="#method.fetch_and" class="fn">fetch_and</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Performs a bitwise “and” operation on the address of the current
pointer, and the argument <code>val</code>, and stores a pointer with provenance of
the current pointer and the resulting address.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a> to atomically perform
<code>ptr = ptr.map_addr(|a| a &amp; val)</code>. This can be used in tagged
pointer schemes to atomically unset tag bits.</p>
<p><strong>Caveat</strong>: This operation returns the previous value. To compute the
stored value without losing provenance, you may use <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a>. For
example: <code>a.fetch_and(val).map_addr(|a| a &amp; val)</code>.</p>
<p><code>fetch_and</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory
ordering of this operation. All ordering modes are possible. Note that
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>,
and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This API and its claimed semantics are part of the Strict Provenance
experiment, see the <a href="https://doc.rust-lang.org/1.82.0/core/ptr/index.html" title="mod core::ptr">module documentation for <code>ptr</code></a> for
details.</p>
<h5 id="examples-16"><a class="doc-anchor" href="#examples-16">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="comment">// A tagged pointer
</span><span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer.map_addr(|a| a | <span class="number">1</span>));
<span class="macro">assert_eq!</span>(atom.fetch_or(<span class="number">1</span>, Ordering::Relaxed).addr() &amp; <span class="number">1</span>, <span class="number">1</span>);
<span class="comment">// Untag, and extract the previously tagged pointer.
</span><span class="kw">let </span>untagged = atom.fetch_and(!<span class="number">1</span>, Ordering::Relaxed).map_addr(|a| a &amp; !<span class="number">1</span>);
<span class="macro">assert_eq!</span>(untagged, pointer);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.fetch_xor" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2318-2333">source</a><h4 class="code-header">pub fn <a href="#method.fetch_xor" class="fn">fetch_xor</a>(&amp;self, val: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.usize.html">usize</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Performs a bitwise “xor” operation on the address of the current
pointer, and the argument <code>val</code>, and stores a pointer with provenance of
the current pointer and the resulting address.</p>
<p>This is equivalent to using <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a> to atomically perform
<code>ptr = ptr.map_addr(|a| a ^ val)</code>. This can be used in tagged
pointer schemes to atomically toggle tag bits.</p>
<p><strong>Caveat</strong>: This operation returns the previous value. To compute the
stored value without losing provenance, you may use <a href="https://doc.rust-lang.org/std/primitive.pointer.html#method.map_addr"><code>map_addr</code></a>. For
example: <code>a.fetch_xor(val).map_addr(|a| a ^ val)</code>.</p>
<p><code>fetch_xor</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory
ordering of this operation. All ordering modes are possible. Note that
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>,
and using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This API and its claimed semantics are part of the Strict Provenance
experiment, see the <a href="https://doc.rust-lang.org/1.82.0/core/ptr/index.html" title="mod core::ptr">module documentation for <code>ptr</code></a> for
details.</p>
<h5 id="examples-17"><a class="doc-anchor" href="#examples-17">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer);
<span class="comment">// Toggle a tag bit on the pointer.
</span>atom.fetch_xor(<span class="number">1</span>, Ordering::Relaxed);
<span class="macro">assert_eq!</span>(atom.load(Ordering::Relaxed).addr() &amp; <span class="number">1</span>, <span class="number">1</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.bit_set" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2365-2381">source</a><h4 class="code-header">pub fn <a href="#method.bit_set" class="fn">bit_set</a>(&amp;self, bit: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.u32.html">u32</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Sets the bit at the specified bit-position to 1.</p>
<p>Returns <code>true</code> if the specified bit was previously set to 1.</p>
<p><code>bit_set</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. All ordering modes are possible. Note that using
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This corresponds to x86’s <code>lock bts</code>, and the implementation calls them on x86/x86_64.</p>
<h5 id="examples-18"><a class="doc-anchor" href="#examples-18">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer);
<span class="comment">// Tag the bottom bit of the pointer.
</span><span class="macro">assert!</span>(!atom.bit_set(<span class="number">0</span>, Ordering::Relaxed));
<span class="comment">// Extract and untag.
</span><span class="kw">let </span>tagged = atom.load(Ordering::Relaxed);
<span class="macro">assert_eq!</span>(tagged.addr() &amp; <span class="number">1</span>, <span class="number">1</span>);
<span class="macro">assert_eq!</span>(tagged.map_addr(|p| p &amp; !<span class="number">1</span>), pointer);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.bit_clear" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2410-2426">source</a><h4 class="code-header">pub fn <a href="#method.bit_clear" class="fn">bit_clear</a>(&amp;self, bit: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.u32.html">u32</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Clears the bit at the specified bit-position to 1.</p>
<p>Returns <code>true</code> if the specified bit was previously set to 1.</p>
<p><code>bit_clear</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. All ordering modes are possible. Note that using
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This corresponds to x86’s <code>lock btr</code>, and the implementation calls them on x86/x86_64.</p>
<h5 id="examples-19"><a class="doc-anchor" href="#examples-19">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="comment">// A tagged pointer
</span><span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer.map_addr(|a| a | <span class="number">1</span>));
<span class="macro">assert!</span>(atom.bit_set(<span class="number">0</span>, Ordering::Relaxed));
<span class="comment">// Untag
</span><span class="macro">assert!</span>(atom.bit_clear(<span class="number">0</span>, Ordering::Relaxed));</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.bit_toggle" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2455-2471">source</a><h4 class="code-header">pub fn <a href="#method.bit_toggle" class="fn">bit_toggle</a>(&amp;self, bit: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.u32.html">u32</a>, order: <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering">Ordering</a>) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.bool.html">bool</a></h4></section></summary><div class="docblock"><p>Toggles the bit at the specified bit-position.</p>
<p>Returns <code>true</code> if the specified bit was previously set to 1.</p>
<p><code>bit_toggle</code> takes an <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html" title="enum core::sync::atomic::Ordering"><code>Ordering</code></a> argument which describes the memory ordering
of this operation. All ordering modes are possible. Note that using
<a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Acquire" title="variant core::sync::atomic::Ordering::Acquire"><code>Acquire</code></a> makes the store part of this operation <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>, and
using <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Release" title="variant core::sync::atomic::Ordering::Release"><code>Release</code></a> makes the load part <a href="https://doc.rust-lang.org/1.82.0/core/sync/atomic/enum.Ordering.html#variant.Relaxed" title="variant core::sync::atomic::Ordering::Relaxed"><code>Relaxed</code></a>.</p>
<p>This corresponds to x86’s <code>lock btc</code>, and the implementation calls them on x86/x86_64.</p>
<h5 id="examples-20"><a class="doc-anchor" href="#examples-20">§</a>Examples</h5>
<div class="example-wrap"><pre class="rust rust-example-rendered"><code><span class="kw">use </span>portable_atomic::{AtomicPtr, Ordering};
<span class="kw">use </span>sptr::Strict; <span class="comment">// stable polyfill for strict provenance
</span><span class="kw">let </span>pointer = <span class="kw-2">&amp;mut </span><span class="number">3i64 </span><span class="kw">as </span><span class="kw-2">*mut </span>i64;
<span class="kw">let </span>atom = AtomicPtr::&lt;i64&gt;::new(pointer);
<span class="comment">// Toggle a tag bit on the pointer.
</span>atom.bit_toggle(<span class="number">0</span>, Ordering::Relaxed);
<span class="macro">assert_eq!</span>(atom.load(Ordering::Relaxed).addr() &amp; <span class="number">1</span>, <span class="number">1</span>);</code></pre></div>
</div></details><details class="toggle method-toggle" open><summary><section id="method.as_ptr" class="method"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#2488-2508">source</a><h4 class="code-header">pub const fn <a href="#method.as_ptr" class="fn">as_ptr</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut </a><a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a></h4></section></summary><div class="docblock"><p>Returns a mutable pointer to the underlying pointer.</p>
<p>Returning an <code>*mut</code> pointer from a shared reference to this atomic is
safe because the atomic types work with interior mutability. Any use of
the returned raw pointer requires an <code>unsafe</code> block and has to uphold
the safety requirements. If there is concurrent access, note the following
additional safety requirements:</p>
<ul>
<li>If this atomic type is <a href="struct.AtomicPtr.html#method.is_lock_free" title="associated function portable_atomic::AtomicPtr::is_lock_free">lock-free</a>, any concurrent
operations on it must be atomic.</li>
<li>Otherwise, any concurrent operations on it must be compatible with
operations performed by this atomic type.</li>
</ul>
<p>This is <code>const fn</code> on Rust 1.58+.</p>
</div></details></div></details></div><h2 id="trait-implementations" class="section-header">Trait Implementations<a href="#trait-implementations" class="anchor">§</a></h2><div id="trait-implementations-list"><details class="toggle implementors-toggle" open><summary><section id="impl-Debug-for-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1555-1561">source</a><a href="#impl-Debug-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Debug.html" title="trait core::fmt::Debug">Debug</a> for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.fmt" class="method trait-impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1557-1560">source</a><a href="#method.fmt" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Debug.html#tymethod.fmt" class="fn">fmt</a>(&amp;self, f: &amp;mut <a class="struct" href="https://doc.rust-lang.org/1.82.0/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>&lt;'_&gt;) -&gt; <a class="type" href="https://doc.rust-lang.org/1.82.0/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></h4></section></summary><div class='docblock'>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Debug.html#tymethod.fmt">Read more</a></div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Default-for-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1540-1546">source</a><a href="#impl-Default-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/default/trait.Default.html" title="trait core::default::Default">Default</a> for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.default" class="method trait-impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1543-1545">source</a><a href="#method.default" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/default/trait.Default.html#tymethod.default" class="fn">default</a>() -&gt; Self</h4></section></summary><div class="docblock"><p>Creates a null <code>AtomicPtr&lt;T&gt;</code>.</p>
</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-From%3C*mut+T%3E-for-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1548-1553">source</a><a href="#impl-From%3C*mut+T%3E-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;<a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>&gt; for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.from" class="method trait-impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1550-1552">source</a><a href="#method.from" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html#tymethod.from" class="fn">from</a>(p: <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.pointer.html">*mut T</a>) -&gt; Self</h4></section></summary><div class='docblock'>Converts to this type from the input type.</div></details></div></details><details class="toggle implementors-toggle" open><summary><section id="impl-Pointer-for-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1563-1569">source</a><a href="#impl-Pointer-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Pointer.html" title="trait core::fmt::Pointer">Pointer</a> for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.fmt-1" class="method trait-impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1565-1568">source</a><a href="#method.fmt-1" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Pointer.html#tymethod.fmt" class="fn">fmt</a>(&amp;self, f: &amp;mut <a class="struct" href="https://doc.rust-lang.org/1.82.0/core/fmt/struct.Formatter.html" title="struct core::fmt::Formatter">Formatter</a>&lt;'_&gt;) -&gt; <a class="type" href="https://doc.rust-lang.org/1.82.0/core/fmt/type.Result.html" title="type core::fmt::Result">Result</a></h4></section></summary><div class='docblock'>Formats the value using the given formatter. <a href="https://doc.rust-lang.org/1.82.0/core/fmt/trait.Pointer.html#tymethod.fmt">Read more</a></div></details></div></details><section id="impl-RefUnwindSafe-for-AtomicPtr%3CT%3E" class="impl"><a class="src rightside" href="../src/portable_atomic/lib.rs.html#1573">source</a><a href="#impl-RefUnwindSafe-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/panic/unwind_safe/trait.RefUnwindSafe.html" title="trait core::panic::unwind_safe::RefUnwindSafe">RefUnwindSafe</a> for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section></div><h2 id="synthetic-implementations" class="section-header">Auto Trait Implementations<a href="#synthetic-implementations" class="anchor">§</a></h2><div id="synthetic-implementations-list"><section id="impl-Freeze-for-AtomicPtr%3CT%3E" class="impl"><a href="#impl-Freeze-for-AtomicPtr%3CT%3E" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; !<a class="trait" href="https://doc.rust-lang.org/1.82.0/core/marker/trait.Freeze.html" title="trait core::marker::Freeze">Freeze</a> for <a class="struct" href="struct.AtomicPtr.html" title="struct portable_atomic::AtomicPtr">AtomicPtr</a>&lt;T&gt;</h3></section><section id="impl-Send-for-AtomicPtr%3CT%3E" class=
T: <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/panic/unwind_safe/trait.RefUnwindSafe.html" title="trait core::panic::unwind_safe::RefUnwindSafe">RefUnwindSafe</a>,</div></h3></section></div><h2 id="blanket-implementations" class="section-header">Blanket Implementations<a href="#blanket-implementations" class="anchor">§</a></h2><div id="blanket-implementations-list"><details class="toggle implementors-toggle"><summary><section id="impl-Any-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/any.rs.html#138">source</a><a href="#impl-Any-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/any/trait.Any.html" title="trait core::any::Any">Any</a> for T<div class="where">where
T: 'static + ?<a class="trait" href="https://doc.rust-lang.org/1.82.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.type_id" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/any.rs.html#139">source</a><a href="#method.type_id" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/any/trait.Any.html#tymethod.type_id" class="fn">type_id</a>(&amp;self) -&gt; <a class="struct" href="https://doc.rust-lang.org/1.82.0/core/any/struct.TypeId.html" title="struct core::any::TypeId">TypeId</a></h4></section></summary><div class='docblock'>Gets the <code>TypeId</code> of <code>self</code>. <a href="https://doc.rust-lang.org/1.82.0/core/any/trait.Any.html#tymethod.type_id">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Borrow%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/borrow.rs.html#209">source</a><a href="#impl-Borrow%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.Borrow.html" title="trait core::borrow::Borrow">Borrow</a>&lt;T&gt; for T<div class="where">where
T: ?<a class="trait" href="https://doc.rust-lang.org/1.82.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.borrow" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/borrow.rs.html#211">source</a><a href="#method.borrow" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.Borrow.html#tymethod.borrow" class="fn">borrow</a>(&amp;self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.reference.html">&amp;T</a></h4></section></summary><div class='docblock'>Immutably borrows from an owned value. <a href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.Borrow.html#tymethod.borrow">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-BorrowMut%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/borrow.rs.html#217">source</a><a href="#impl-BorrowMut%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.BorrowMut.html" title="trait core::borrow::BorrowMut">BorrowMut</a>&lt;T&gt; for T<div class="where">where
T: ?<a class="trait" href="https://doc.rust-lang.org/1.82.0/core/marker/trait.Sized.html" title="trait core::marker::Sized">Sized</a>,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.borrow_mut" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/borrow.rs.html#218">source</a><a href="#method.borrow_mut" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut" class="fn">borrow_mut</a>(&amp;mut self) -&gt; <a class="primitive" href="https://doc.rust-lang.org/1.82.0/core/primitive.reference.html">&amp;mut T</a></h4></section></summary><div class='docblock'>Mutably borrows from an owned value. <a href="https://doc.rust-lang.org/1.82.0/core/borrow/trait.BorrowMut.html#tymethod.borrow_mut">Read more</a></div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-From%3CT%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#765">source</a><a href="#impl-From%3CT%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt; for T</h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.from-1" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#768">source</a><a href="#method.from-1" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html#tymethod.from" class="fn">from</a>(t: T) -&gt; T</h4></section></summary><div class="docblock"><p>Returns the argument unchanged.</p>
</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-Into%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#748-750">source</a><a href="#impl-Into%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle method-toggle" open><summary><section id="method.into" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#758">source</a><a href="#method.into" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.Into.html#tymethod.into" class="fn">into</a>(self) -&gt; U</h4></section></summary><div class="docblock"><p>Calls <code>U::from(self)</code>.</p>
<p>That is, this conversion is whatever the implementation of
<code><a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.From.html" title="trait core::convert::From">From</a>&lt;T&gt; for U</code> chooses to do.</p>
</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-TryFrom%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#805-807">source</a><a href="#impl-TryFrom%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.Into.html" title="trait core::convert::Into">Into</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle" open><summary><section id="associatedtype.Error-1" class="associatedtype trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#809">source</a><a href="#associatedtype.Error-1" class="anchor">§</a><h4 class="code-header">type <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html#associatedtype.Error" class="associatedtype">Error</a> = <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/convert/enum.Infallible.html" title="enum core::convert::Infallible">Infallible</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="toggle method-toggle" open><summary><section id="method.try_from" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#812">source</a><a href="#method.try_from" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html#tymethod.try_from" class="fn">try_from</a>(value: U) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;T, &lt;T as <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;U&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details><details class="toggle implementors-toggle"><summary><section id="impl-TryInto%3CU%3E-for-T" class="impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#790-792">source</a><a href="#impl-TryInto%3CU%3E-for-T" class="anchor">§</a><h3 class="code-header">impl&lt;T, U&gt; <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryInto.html" title="trait core::convert::TryInto">TryInto</a>&lt;U&gt; for T<div class="where">where
U: <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;,</div></h3></section></summary><div class="impl-items"><details class="toggle" open><summary><section id="associatedtype.Error" class="associatedtype trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#794">source</a><a href="#associatedtype.Error" class="anchor">§</a><h4 class="code-header">type <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryInto.html#associatedtype.Error" class="associatedtype">Error</a> = &lt;U as <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a></h4></section></summary><div class='docblock'>The type returned in the event of a conversion error.</div></details><details class="toggle method-toggle" open><summary><section id="method.try_into" class="method trait-impl"><a class="src rightside" href="https://doc.rust-lang.org/1.82.0/src/core/convert/mod.rs.html#797">source</a><a href="#method.try_into" class="anchor">§</a><h4 class="code-header">fn <a href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryInto.html#tymethod.try_into" class="fn">try_into</a>(self) -&gt; <a class="enum" href="https://doc.rust-lang.org/1.82.0/core/result/enum.Result.html" title="enum core::result::Result">Result</a>&lt;U, &lt;U as <a class="trait" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html" title="trait core::convert::TryFrom">TryFrom</a>&lt;T&gt;&gt;::<a class="associatedtype" href="https://doc.rust-lang.org/1.82.0/core/convert/trait.TryFrom.html#associatedtype.Error" title="type core::convert::TryFrom::Error">Error</a>&gt;</h4></section></summary><div class='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main></body></html>
Reference in a new issue Copy permalink