<!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="API documentation for the Rust `rc` mod in crate `alloc`."><meta name="keywords" content="rust, rustlang, rust-lang, rc"><title>alloc::rc - Rust</title><link rel="stylesheet" type="text/css" href="../../normalize.css"><link rel="stylesheet" type="text/css" href="../../rustdoc.css" id="mainThemeStyle"><link rel="stylesheet" type="text/css" href="../../dark.css"><link rel="stylesheet" type="text/css" href="../../light.css" id="themeStyle"><script src="../../storage.js"></script><link rel="shortcut icon" href="https://doc.rust-lang.org/favicon.ico"></head><body class="rustdoc mod"><!--[if lte IE 8]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu">☰</div><a href='../../alloc/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Module rc</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li></ul></div><p class='location'><a href='../index.html'>alloc</a></p><script>window.sidebarCurrent = {name: 'rc', ty: 'mod', relpath: '../'};</script><script defer src="../sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!"><img src="../../brush.svg" width="18" alt="Pick another theme!"></button><div id="theme-choices"></div></div><script src="../../theme.js"></script><nav class="sub"><form class="search-form js-only"><div class="search-container"><input class="search-input" name="search" autocomplete="off" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"><a id="settings-menu" href="../../settings.html"><img src="../../wheel.svg" width="18" alt="Change settings"></a></div></form></nav><section id="main" class="content"><h1 class='fqn'><span class='in-band'>Module <a href='../index.html'>alloc</a>::<wbr><a class="mod" href=''>rc</a></span><span class='out-of-band'><span class='since' title='Stable since Rust version 1.0.0'>1.0.0</span><span id='render-detail'><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class='inner'>−</span>]</a></span><a class='srclink' href='../../src/alloc/rc.rs.html#11-1798' title='goto source code'>[src]</a></span></h1><div class='docblock'><p>Single-threaded reference-counting pointers. 'Rc' stands for 'Reference
Counted'.</p>
<p>The type <a href="struct.Rc.html"><code>Rc<T></code></a> provides shared ownership of a value of type <code>T</code>,
allocated in the heap. Invoking <a href="../../std/clone/trait.Clone.html#tymethod.clone"><code>clone</code></a> on <a href="struct.Rc.html"><code>Rc</code></a> produces a new
pointer to the same value in the heap. When the last <a href="struct.Rc.html"><code>Rc</code></a> pointer to a
given value is destroyed, the pointed-to value is also destroyed.</p>
<p>Shared references in Rust disallow mutation by default, and <a href="struct.Rc.html"><code>Rc</code></a>
is no exception: you cannot generally obtain a mutable reference to
something inside an <a href="struct.Rc.html"><code>Rc</code></a>. If you need mutability, put a <a href="../../std/cell/struct.Cell.html"><code>Cell</code></a>
or <a href="../../std/cell/struct.RefCell.html"><code>RefCell</code></a> inside the <a href="struct.Rc.html"><code>Rc</code></a>; see <a href="../../std/cell/index.html#introducing-mutability-inside-of-something-immutable">an example of mutability
inside an Rc</a>.</p>
<p><a href="struct.Rc.html"><code>Rc</code></a> uses non-atomic reference counting. This means that overhead is very
low, but an <a href="struct.Rc.html"><code>Rc</code></a> cannot be sent between threads, and consequently <a href="struct.Rc.html"><code>Rc</code></a>
does not implement <a href="../../std/marker/trait.Send.html"><code>Send</code></a>. As a result, the Rust compiler
will check <em>at compile time</em> that you are not sending <a href="struct.Rc.html"><code>Rc</code></a>s between
threads. If you need multi-threaded, atomic reference counting, use
<a href="../../std/sync/struct.Arc.html"><code>sync::Arc</code></a>.</p>
<p>The <a href="struct.Rc.html#method.downgrade"><code>downgrade</code></a> method can be used to create a non-owning
<a href="struct.Weak.html"><code>Weak</code></a> pointer. A <a href="struct.Weak.html"><code>Weak</code></a> pointer can be <a href="struct.Weak.html#method.upgrade"><code>upgrade</code></a>d
to an <a href="struct.Rc.html"><code>Rc</code></a>, but this will return <a href="../../std/option/enum.Option.html#variant.None"><code>None</code></a> if the value has
already been dropped.</p>
<p>A cycle between <a href="struct.Rc.html"><code>Rc</code></a> pointers will never be deallocated. For this reason,
<a href="struct.Weak.html"><code>Weak</code></a> is used to break cycles. For example, a tree could have strong
<a href="struct.Rc.html"><code>Rc</code></a> pointers from parent nodes to children, and <a href="struct.Weak.html"><code>Weak</code></a> pointers from
children back to their parents.</p>
<p><code>Rc<T></code> automatically dereferences to <code>T</code> (via the <a href="../../std/ops/trait.Deref.html"><code>Deref</code></a> trait),
so you can call <code>T</code>'s methods on a value of type <a href="struct.Rc.html"><code>Rc<T></code></a>. To avoid name
clashes with <code>T</code>'s methods, the methods of <a href="struct.Rc.html"><code>Rc<T></code></a> itself are <a href="../../book/first-edition/method-syntax.html#associated-functions">associated
functions</a>, called using function-like syntax:</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">rc</span>::<span class="ident">Rc</span>;
<span class="kw">let</span> <span class="ident">my_rc</span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(());
<span class="ident">Rc</span>::<span class="ident">downgrade</span>(<span class="kw-2">&</span><span class="ident">my_rc</span>);</pre>
<p><a href="struct.Weak.html"><code>Weak<T></code></a> does not auto-dereference to <code>T</code>, because the value may have
already been destroyed.</p>
<h1 id="cloning-references" class="section-header"><a href="#cloning-references">Cloning references</a></h1>
<p>Creating a new reference from an existing reference counted pointer is done using the
<code>Clone</code> trait implemented for <a href="struct.Rc.html"><code>Rc<T></code></a> and <a href="struct.Weak.html"><code>Weak<T></code></a>.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">rc</span>::<span class="ident">Rc</span>;
<span class="kw">let</span> <span class="ident">foo</span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(<span class="macro">vec</span><span class="macro">!</span>[<span class="number">1.0</span>, <span class="number">2.0</span>, <span class="number">3.0</span>]);
<span class="comment">// The two syntaxes below are equivalent.</span>
<span class="kw">let</span> <span class="ident">a</span> <span class="op">=</span> <span class="ident">foo</span>.<span class="ident">clone</span>();
<span class="kw">let</span> <span class="ident">b</span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">clone</span>(<span class="kw-2">&</span><span class="ident">foo</span>);
<span class="comment">// a and b both point to the same memory location as foo.</span></pre>
<p>The <code>Rc::clone(&from)</code> syntax is the most idiomatic because it conveys more explicitly
the meaning of the code. In the example above, this syntax makes it easier to see that
this code is creating a new reference rather than copying the whole content of foo.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<p>Consider a scenario where a set of <code>Gadget</code>s are owned by a given <code>Owner</code>.
We want to have our <code>Gadget</code>s point to their <code>Owner</code>. We can't do this with
unique ownership, because more than one gadget may belong to the same
<code>Owner</code>. <a href="struct.Rc.html"><code>Rc</code></a> allows us to share an <code>Owner</code> between multiple <code>Gadget</code>s,
and have the <code>Owner</code> remain allocated as long as any <code>Gadget</code> points at it.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">rc</span>::<span class="ident">Rc</span>;
<span class="kw">struct</span> <span class="ident">Owner</span> {
<span class="ident">name</span>: <span class="ident">String</span>,
<span class="comment">// ...other fields</span>
}
<span class="kw">struct</span> <span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="ident">i32</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span><span class="op"><</span><span class="ident">Owner</span><span class="op">></span>,
<span class="comment">// ...other fields</span>
}
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="comment">// Create a reference-counted `Owner`.</span>
<span class="kw">let</span> <span class="ident">gadget_owner</span>: <span class="ident">Rc</span><span class="op"><</span><span class="ident">Owner</span><span class="op">></span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(
<span class="ident">Owner</span> {
<span class="ident">name</span>: <span class="string">"Gadget Man"</span>.<span class="ident">to_string</span>(),
}
);
<span class="comment">// Create `Gadget`s belonging to `gadget_owner`. Cloning the `Rc<Owner>`</span>
<span class="comment">// value gives us a new pointer to the same `Owner` value, incrementing</span>
<span class="comment">// the reference count in the process.</span>
<span class="kw">let</span> <span class="ident">gadget1</span> <span class="op">=</span> <span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="number">1</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span>::<span class="ident">clone</span>(<span class="kw-2">&</span><span class="ident">gadget_owner</span>),
};
<span class="kw">let</span> <span class="ident">gadget2</span> <span class="op">=</span> <span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="number">2</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span>::<span class="ident">clone</span>(<span class="kw-2">&</span><span class="ident">gadget_owner</span>),
};
<span class="comment">// Dispose of our local variable `gadget_owner`.</span>
<span class="ident">drop</span>(<span class="ident">gadget_owner</span>);
<span class="comment">// Despite dropping `gadget_owner`, we're still able to print out the name</span>
<span class="comment">// of the `Owner` of the `Gadget`s. This is because we've only dropped a</span>
<span class="comment">// single `Rc<Owner>`, not the `Owner` it points to. As long as there are</span>
<span class="comment">// other `Rc<Owner>` values pointing at the same `Owner`, it will remain</span>
<span class="comment">// allocated. The field projection `gadget1.owner.name` works because</span>
<span class="comment">// `Rc<Owner>` automatically dereferences to `Owner`.</span>
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Gadget {} owned by {}"</span>, <span class="ident">gadget1</span>.<span class="ident">id</span>, <span class="ident">gadget1</span>.<span class="ident">owner</span>.<span class="ident">name</span>);
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Gadget {} owned by {}"</span>, <span class="ident">gadget2</span>.<span class="ident">id</span>, <span class="ident">gadget2</span>.<span class="ident">owner</span>.<span class="ident">name</span>);
<span class="comment">// At the end of the function, `gadget1` and `gadget2` are destroyed, and</span>
<span class="comment">// with them the last counted references to our `Owner`. Gadget Man now</span>
<span class="comment">// gets destroyed as well.</span>
}</pre>
<p>If our requirements change, and we also need to be able to traverse from
<code>Owner</code> to <code>Gadget</code>, we will run into problems. An <a href="struct.Rc.html"><code>Rc</code></a> pointer from <code>Owner</code>
to <code>Gadget</code> introduces a cycle between the values. This means that their
reference counts can never reach 0, and the values will remain allocated
forever: a memory leak. In order to get around this, we can use <a href="struct.Weak.html"><code>Weak</code></a>
pointers.</p>
<p>Rust actually makes it somewhat difficult to produce this loop in the first
place. In order to end up with two values that point at each other, one of
them needs to be mutable. This is difficult because <a href="struct.Rc.html"><code>Rc</code></a> enforces
memory safety by only giving out shared references to the value it wraps,
and these don't allow direct mutation. We need to wrap the part of the
value we wish to mutate in a <a href="../../std/cell/struct.RefCell.html"><code>RefCell</code></a>, which provides <em>interior
mutability</em>: a method to achieve mutability through a shared reference.
<a href="../../std/cell/struct.RefCell.html"><code>RefCell</code></a> enforces Rust's borrowing rules at runtime.</p>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">rc</span>::<span class="ident">Rc</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">rc</span>::<span class="ident">Weak</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">cell</span>::<span class="ident">RefCell</span>;
<span class="kw">struct</span> <span class="ident">Owner</span> {
<span class="ident">name</span>: <span class="ident">String</span>,
<span class="ident">gadgets</span>: <span class="ident">RefCell</span><span class="op"><</span><span class="ident">Vec</span><span class="op"><</span><span class="ident">Weak</span><span class="op"><</span><span class="ident">Gadget</span><span class="op">>></span><span class="op">></span>,
<span class="comment">// ...other fields</span>
}
<span class="kw">struct</span> <span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="ident">i32</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span><span class="op"><</span><span class="ident">Owner</span><span class="op">></span>,
<span class="comment">// ...other fields</span>
}
<span class="kw">fn</span> <span class="ident">main</span>() {
<span class="comment">// Create a reference-counted `Owner`. Note that we've put the `Owner`'s</span>
<span class="comment">// vector of `Gadget`s inside a `RefCell` so that we can mutate it through</span>
<span class="comment">// a shared reference.</span>
<span class="kw">let</span> <span class="ident">gadget_owner</span>: <span class="ident">Rc</span><span class="op"><</span><span class="ident">Owner</span><span class="op">></span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(
<span class="ident">Owner</span> {
<span class="ident">name</span>: <span class="string">"Gadget Man"</span>.<span class="ident">to_string</span>(),
<span class="ident">gadgets</span>: <span class="ident">RefCell</span>::<span class="ident">new</span>(<span class="macro">vec</span><span class="macro">!</span>[]),
}
);
<span class="comment">// Create `Gadget`s belonging to `gadget_owner`, as before.</span>
<span class="kw">let</span> <span class="ident">gadget1</span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(
<span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="number">1</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span>::<span class="ident">clone</span>(<span class="kw-2">&</span><span class="ident">gadget_owner</span>),
}
);
<span class="kw">let</span> <span class="ident">gadget2</span> <span class="op">=</span> <span class="ident">Rc</span>::<span class="ident">new</span>(
<span class="ident">Gadget</span> {
<span class="ident">id</span>: <span class="number">2</span>,
<span class="ident">owner</span>: <span class="ident">Rc</span>::<span class="ident">clone</span>(<span class="kw-2">&</span><span class="ident">gadget_owner</span>),
}
);
<span class="comment">// Add the `Gadget`s to their `Owner`.</span>
{
<span class="kw">let</span> <span class="kw-2">mut</span> <span class="ident">gadgets</span> <span class="op">=</span> <span class="ident">gadget_owner</span>.<span class="ident">gadgets</span>.<span class="ident">borrow_mut</span>();
<span class="ident">gadgets</span>.<span class="ident">push</span>(<span class="ident">Rc</span>::<span class="ident">downgrade</span>(<span class="kw-2">&</span><span class="ident">gadget1</span>));
<span class="ident">gadgets</span>.<span class="ident">push</span>(<span class="ident">Rc</span>::<span class="ident">downgrade</span>(<span class="kw-2">&</span><span class="ident">gadget2</span>));
<span class="comment">// `RefCell` dynamic borrow ends here.</span>
}
<span class="comment">// Iterate over our `Gadget`s, printing their details out.</span>
<span class="kw">for</span> <span class="ident">gadget_weak</span> <span class="kw">in</span> <span class="ident">gadget_owner</span>.<span class="ident">gadgets</span>.<span class="ident">borrow</span>().<span class="ident">iter</span>() {
<span class="comment">// `gadget_weak` is a `Weak<Gadget>`. Since `Weak` pointers can't</span>
<span class="comment">// guarantee the value is still allocated, we need to call</span>
<span class="comment">// `upgrade`, which returns an `Option<Rc<Gadget>>`.</span>
<span class="comment">//</span>
<span class="comment">// In this case we know the value still exists, so we simply</span>
<span class="comment">// `unwrap` the `Option`. In a more complicated program, you might</span>
<span class="comment">// need graceful error handling for a `None` result.</span>
<span class="kw">let</span> <span class="ident">gadget</span> <span class="op">=</span> <span class="ident">gadget_weak</span>.<span class="ident">upgrade</span>().<span class="ident">unwrap</span>();
<span class="macro">println</span><span class="macro">!</span>(<span class="string">"Gadget {} owned by {}"</span>, <span class="ident">gadget</span>.<span class="ident">id</span>, <span class="ident">gadget</span>.<span class="ident">owner</span>.<span class="ident">name</span>);
}
<span class="comment">// At the end of the function, `gadget_owner`, `gadget1`, and `gadget2`</span>
<span class="comment">// are destroyed. There are now no strong (`Rc`) pointers to the</span>
<span class="comment">// gadgets, so they are destroyed. This zeroes the reference count on</span>
<span class="comment">// Gadget Man, so he gets destroyed as well.</span>
}</pre>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.Rc.html"
title='struct alloc::rc::Rc'>Rc</a></td>
<td class='docblock-short'>
<p>A single-threaded reference-counting pointer. 'Rc' stands for 'Reference
Counted'.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Weak.html"
title='struct alloc::rc::Weak'>Weak</a></td>
<td class='docblock-short'>
<p><code>Weak</code> is a version of <a href="struct.Rc.html"><code>Rc</code></a> that holds a non-owning reference to the
managed value. The value is accessed by calling <a href="struct.Weak.html#method.upgrade"><code>upgrade</code></a> on the <code>Weak</code>
pointer, which returns an <a href="../../std/option/enum.Option.html"><code>Option</code></a><code><</code><a href="struct.Rc.html"><code>Rc</code></a><code><T>></code>.</p>
</td>
</tr></table></section><section id="search" class="content hidden"></section><section class="footer"></section><aside id="help" class="hidden"><div><h1 class="hidden">Help</h1><div class="shortcuts"><h2>Keyboard Shortcuts</h2><dl><dt><kbd>?</kbd></dt><dd>Show this help dialog</dd><dt><kbd>S</kbd></dt><dd>Focus the search field</dd><dt><kbd>↑</kbd></dt><dd>Move up in search results</dd><dt><kbd>↓</kbd></dt><dd>Move down in search results</dd><dt><kbd>↹</kbd></dt><dd>Switch tab</dd><dt><kbd>⏎</kbd></dt><dd>Go to active search result</dd><dt><kbd>+</kbd></dt><dd>Expand all sections</dd><dt><kbd>-</kbd></dt><dd>Collapse all sections</dd></dl></div><div class="infos"><h2>Search Tricks</h2><p>Prefix searches with a type followed by a colon (e.g. <code>fn:</code>) to restrict the search to a given type.</p><p>Accepted types are: <code>fn</code>, <code>mod</code>, <code>struct</code>, <code>enum</code>, <code>trait</code>, <code>type</code>, <code>macro</code>, and <code>const</code>.</p><p>Search functions by type signature (e.g. <code>vec -> usize</code> or <code>* -> vec</code>)</p><p>Search multiple things at once by splitting your query with comma (e.g. <code>str,u8</code> or <code>String,struct:Vec,test</code>)</p></div></div></aside><script>window.rootPath = "../../";window.currentCrate = "alloc";</script><script src="../../aliases.js"></script><script src="../../main.js"></script><script defer src="../../search-index.js"></script></body></html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
4e2dbb669434a7691662cb2f0ad38972
>
files
>
257
