<!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 `Once` struct in crate `std`."><meta name="keywords" content="rust, rustlang, rust-lang, Once"><title>std::sync::Once - 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 struct"><!--[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='../../std/index.html'><img src='https://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png' alt='logo' width='100'></a><p class='location'>Struct Once</p><div class="sidebar-elems"><div class="block items"><a class="sidebar-title" href="#methods">Methods</a><div class="sidebar-links"><a href="#method.new">new</a><a href="#method.call_once">call_once</a><a href="#method.call_once_force">call_once_force</a></div><a class="sidebar-title" href="#implementations">Trait Implementations</a><div class="sidebar-links"><a href="#impl-Sync">Sync</a><a href="#impl-Send">Send</a><a href="#impl-Debug">Debug</a></div></div><p class='location'><a href='../index.html'>std</a>::<wbr><a href='index.html'>sync</a></p><script>window.sidebarCurrent = {name: 'Once', ty: 'struct', 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'>Struct <a href='../index.html'>std</a>::<wbr><a href='index.html'>sync</a>::<wbr><a class="struct" href=''>Once</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/std/sync/once.rs.html#93-98' title='goto source code'>[src]</a></span></h1><div class="docblock type-decl"><pre class='rust struct'>pub struct Once { /* fields omitted */ }</pre></div><div class='docblock'><p>A synchronization primitive which can be used to run a one-time global
initialization. Useful for one-time initialization for FFI or related
functionality. This type can only be constructed with the <a href="constant.ONCE_INIT.html"><code>ONCE_INIT</code></a>
value or the equivalent <a href="struct.Once.html#method.new"><code>Once::new</code></a> constructor.</p>
<h1 id="examples" class="section-header"><a href="#examples">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">sync</span>::<span class="ident">Once</span>;
<span class="kw">static</span> <span class="ident">START</span>: <span class="ident">Once</span> <span class="op">=</span> <span class="ident">Once</span>::<span class="ident">new</span>();
<span class="ident">START</span>.<span class="ident">call_once</span>(<span class="op">||</span> {
<span class="comment">// run initialization here</span>
});<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Async%3A%3AOnce%3B%0A%0Astatic%20START%3A%20Once%20%3D%20Once%3A%3Anew()%3B%0A%0ASTART.call_once(%7C%7C%20%7B%0A%20%20%20%20%2F%2F%20run%20initialization%20here%0A%7D)%3B%0A%7D">Run</a></pre>
</div>
<h2 id='methods' class='small-section-header'>
Methods<a href='#methods' class='anchor'></a>
</h2>
<h3 id='impl' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="struct" href="../../std/sync/struct.Once.html" title="struct std::sync::Once">Once</a></code><a href='#impl' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#157-384' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.new' class="method"><span id='new.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub const fn <a href='#method.new' class='fnname'>new</a>() -> <a class="struct" href="../../std/sync/struct.Once.html" title="struct std::sync::Once">Once</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><div class='since' title='Stable since Rust version 1.2.0'>1.2.0</div><a class='srclink' href='../../src/std/sync/once.rs.html#160-165' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Creates a new <code>Once</code> value.</p>
</div><h4 id='method.call_once' class="method"><span id='call_once.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.call_once' class='fnname'>call_once</a><F>(&'static self, f: F) <span class="where fmt-newline">where<br> F: <a class="trait" href="../../std/ops/trait.FnOnce.html" title="trait std::ops::FnOnce">FnOnce</a>(), </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#221-229' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Performs an initialization routine once and only once. The given closure
will be executed if this is the first time <code>call_once</code> has been called,
and otherwise the routine will <em>not</em> be invoked.</p>
<p>This method will block the calling thread if another initialization
routine is currently running.</p>
<p>When this function returns, it is guaranteed that some initialization
has run and completed (it may not be the closure specified). It is also
guaranteed that any memory writes performed by the executed closure can
be reliably observed by other threads at this point (there is a
happens-before relation between the closure and code executing after the
return).</p>
<h1 id="examples-1" class="section-header"><a href="#examples-1">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">sync</span>::<span class="ident">Once</span>;
<span class="kw">static</span> <span class="kw-2">mut</span> <span class="ident">VAL</span>: <span class="ident">usize</span> <span class="op">=</span> <span class="number">0</span>;
<span class="kw">static</span> <span class="ident">INIT</span>: <span class="ident">Once</span> <span class="op">=</span> <span class="ident">Once</span>::<span class="ident">new</span>();
<span class="comment">// Accessing a `static mut` is unsafe much of the time, but if we do so</span>
<span class="comment">// in a synchronized fashion (e.g. write once or read all) then we're</span>
<span class="comment">// good to go!</span>
<span class="comment">//</span>
<span class="comment">// This function will only call `expensive_computation` once, and will</span>
<span class="comment">// otherwise always return the value returned from the first invocation.</span>
<span class="kw">fn</span> <span class="ident">get_cached_val</span>() <span class="op">-></span> <span class="ident">usize</span> {
<span class="kw">unsafe</span> {
<span class="ident">INIT</span>.<span class="ident">call_once</span>(<span class="op">||</span> {
<span class="ident">VAL</span> <span class="op">=</span> <span class="ident">expensive_computation</span>();
});
<span class="ident">VAL</span>
}
}
<span class="kw">fn</span> <span class="ident">expensive_computation</span>() <span class="op">-></span> <span class="ident">usize</span> {
<span class="comment">// ...</span>
}<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0Afn%20main()%20%7B%0Ause%20std%3A%3Async%3A%3AOnce%3B%0A%0Astatic%20mut%20VAL%3A%20usize%20%3D%200%3B%0Astatic%20INIT%3A%20Once%20%3D%20Once%3A%3Anew()%3B%0A%0A%2F%2F%20Accessing%20a%20%60static%20mut%60%20is%20unsafe%20much%20of%20the%20time%2C%20but%20if%20we%20do%20so%0A%2F%2F%20in%20a%20synchronized%20fashion%20(e.g.%20write%20once%20or%20read%20all)%20then%20we're%0A%2F%2F%20good%20to%20go!%0A%2F%2F%0A%2F%2F%20This%20function%20will%20only%20call%20%60expensive_computation%60%20once%2C%20and%20will%0A%2F%2F%20otherwise%20always%20return%20the%20value%20returned%20from%20the%20first%20invocation.%0Afn%20get_cached_val()%20-%3E%20usize%20%7B%0A%20%20%20%20unsafe%20%7B%0A%20%20%20%20%20%20%20%20INIT.call_once(%7C%7C%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20VAL%20%3D%20expensive_computation()%3B%0A%20%20%20%20%20%20%20%20%7D)%3B%0A%20%20%20%20%20%20%20%20VAL%0A%20%20%20%20%7D%0A%7D%0A%0Afn%20expensive_computation()%20-%3E%20usize%20%7B%0A%20%20%20%20%2F%2F%20...%0A2%0A%7D%0A%7D">Run</a></pre>
<h1 id="panics" class="section-header"><a href="#panics">Panics</a></h1>
<p>The closure <code>f</code> will only be executed once if this is called
concurrently amongst many threads. If that closure panics, however, then
it will <em>poison</em> this <code>Once</code> instance, causing all future invocations of
<code>call_once</code> to also panic.</p>
<p>This is similar to <a href="struct.Mutex.html#poisoning">poisoning with mutexes</a>.</p>
</div><h4 id='method.call_once_force' class="method"><span id='call_once_force.v' class='invisible'><table class='table-display'><tbody><tr><td><code>pub fn <a href='#method.call_once_force' class='fnname'>call_once_force</a><F>(&'static self, f: F) <span class="where fmt-newline">where<br> F: <a class="trait" href="../../std/ops/trait.FnOnce.html" title="trait std::ops::FnOnce">FnOnce</a>(&<a class="struct" href="../../std/sync/struct.OnceState.html" title="struct std::sync::OnceState">OnceState</a>), </span></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#278-288' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='stability'><div class='stab unstable'><span class=microscope>🔬</span> This is a nightly-only experimental API. (<code>once_poison </code><a href="https://github.com/rust-lang/rust/issues/33577">#33577</a>)</div></div><div class='docblock'><p>Performs the same function as <a href="struct.Once.html#method.call_once"><code>call_once</code></a> except ignores poisoning.</p>
<p>Unlike <a href="struct.Once.html#method.call_once"><code>call_once</code></a>, if this <code>Once</code> has been poisoned (i.e. a previous
call to <code>call_once</code> or <code>call_once_force</code> caused a panic), calling
<code>call_once_force</code> will still invoke the closure <code>f</code> and will <em>not</em>
result in an immediate panic. If <code>f</code> panics, the <code>Once</code> will remain
in a poison state. If <code>f</code> does <em>not</em> panic, the <code>Once</code> will no
longer be in a poison state and all future calls to <code>call_once</code> or
<code>call_one_force</code> will no-op.</p>
<p>The closure <code>f</code> is yielded a <a href="struct.OnceState.html"><code>OnceState</code></a> structure which can be used
to query the poison status of the <code>Once</code>.</p>
<h1 id="examples-2" class="section-header"><a href="#examples-2">Examples</a></h1>
<pre class="rust rust-example-rendered">
<span class="attribute">#![<span class="ident">feature</span>(<span class="ident">once_poison</span>)]</span>
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">sync</span>::<span class="ident">Once</span>;
<span class="kw">use</span> <span class="ident">std</span>::<span class="ident">thread</span>;
<span class="kw">static</span> <span class="ident">INIT</span>: <span class="ident">Once</span> <span class="op">=</span> <span class="ident">Once</span>::<span class="ident">new</span>();
<span class="comment">// poison the once</span>
<span class="kw">let</span> <span class="ident">handle</span> <span class="op">=</span> <span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="op">||</span> {
<span class="ident">INIT</span>.<span class="ident">call_once</span>(<span class="op">||</span> <span class="macro">panic</span><span class="macro">!</span>());
});
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">handle</span>.<span class="ident">join</span>().<span class="ident">is_err</span>());
<span class="comment">// poisoning propagates</span>
<span class="kw">let</span> <span class="ident">handle</span> <span class="op">=</span> <span class="ident">thread</span>::<span class="ident">spawn</span>(<span class="op">||</span> {
<span class="ident">INIT</span>.<span class="ident">call_once</span>(<span class="op">||</span> {});
});
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">handle</span>.<span class="ident">join</span>().<span class="ident">is_err</span>());
<span class="comment">// call_once_force will still run and reset the poisoned state</span>
<span class="ident">INIT</span>.<span class="ident">call_once_force</span>(<span class="op">|</span><span class="ident">state</span><span class="op">|</span> {
<span class="macro">assert</span><span class="macro">!</span>(<span class="ident">state</span>.<span class="ident">poisoned</span>());
});
<span class="comment">// once any success happens, we stop propagating the poison</span>
<span class="ident">INIT</span>.<span class="ident">call_once</span>(<span class="op">||</span> {});<a class="test-arrow" target="_blank" href="https://play.rust-lang.org/?code=%23!%5Ballow(unused)%5D%0A%23!%5Bfeature(once_poison)%5D%0A%0Afn%20main()%20%7B%0Ause%20std%3A%3Async%3A%3AOnce%3B%0Ause%20std%3A%3Athread%3B%0A%0Astatic%20INIT%3A%20Once%20%3D%20Once%3A%3Anew()%3B%0A%0A%2F%2F%20poison%20the%20once%0Alet%20handle%20%3D%20thread%3A%3Aspawn(%7C%7C%20%7B%0A%20%20%20%20INIT.call_once(%7C%7C%20panic!())%3B%0A%7D)%3B%0Aassert!(handle.join().is_err())%3B%0A%0A%2F%2F%20poisoning%20propagates%0Alet%20handle%20%3D%20thread%3A%3Aspawn(%7C%7C%20%7B%0A%20%20%20%20INIT.call_once(%7C%7C%20%7B%7D)%3B%0A%7D)%3B%0Aassert!(handle.join().is_err())%3B%0A%0A%2F%2F%20call_once_force%20will%20still%20run%20and%20reset%20the%20poisoned%20state%0AINIT.call_once_force(%7Cstate%7C%20%7B%0A%20%20%20%20assert!(state.poisoned())%3B%0A%7D)%3B%0A%0A%2F%2F%20once%20any%20success%20happens%2C%20we%20stop%20propagating%20the%20poison%0AINIT.call_once(%7C%7C%20%7B%7D)%3B%0A%7D&version=nightly">Run</a></pre>
</div></div>
<h2 id='implementations' class='small-section-header'>
Trait Implementations<a href='#implementations' class='anchor'></a>
</h2>
<div id='implementations-list'><h3 id='impl-Sync' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="../../std/marker/trait.Sync.html" title="trait std::marker::Sync">Sync</a> for <a class="struct" href="../../std/sync/struct.Once.html" title="struct std::sync::Once">Once</a></code><a href='#impl-Sync' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#103' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Send' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="../../std/marker/trait.Send.html" title="trait std::marker::Send">Send</a> for <a class="struct" href="../../std/sync/struct.Once.html" title="struct std::sync::Once">Once</a></code><a href='#impl-Send' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#105' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'></div><h3 id='impl-Debug' class='impl'><span class='in-band'><table class='table-display'><tbody><tr><td><code>impl <a class="trait" href="../../std/fmt/trait.Debug.html" title="trait std::fmt::Debug">Debug</a> for <a class="struct" href="../../std/sync/struct.Once.html" title="struct std::sync::Once">Once</a></code><a href='#impl-Debug' class='anchor'></a></span></td><td><span class='out-of-band'><div class='ghost'></div><div class='since' title='Stable since Rust version 1.16.0'>1.16.0</div><a class='srclink' href='../../src/std/sync/once.rs.html#387-391' title='goto source code'>[src]</a></span></td></tr></tbody></table></h3><div class='impl-items'><h4 id='method.fmt' class="method"><span id='fmt.v' class='invisible'><table class='table-display'><tbody><tr><td><code>fn <a href='../../std/fmt/trait.Debug.html#tymethod.fmt' class='fnname'>fmt</a>(&self, f: &mut <a class="struct" href="../../std/fmt/struct.Formatter.html" title="struct std::fmt::Formatter">Formatter</a>) -> <a class="type" href="../../std/fmt/type.Result.html" title="type std::fmt::Result">Result</a></code></span></td><td><span class='out-of-band'><div class='ghost'></div><a class='srclink' href='../../src/std/sync/once.rs.html#388-390' title='goto source code'>[src]</a></td></tr></tbody></table></span></h4><div class='docblock'><p>Formats the value using the given formatter. <a href="../../std/fmt/trait.Debug.html#tymethod.fmt">Read more</a></p>
</div></div></div></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 = "std";</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
>
14877
