<!DOCTYPE html><htmllang="en"><head><metacharset="utf-8"><metaname="viewport"content="width=device-width, initial-scale=1.0"><metaname="generator"content="rustdoc"><metaname="description"content="A mutex based on critical sections."><title>Mutex in critical_section - Rust</title><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceSerif4-Regular-46f98efaafac5295.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Regular-018c141bf0843ffd.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/FiraSans-Medium-8f9a781e4970d388.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Regular-562dcc5011b6de7d.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceSerif4-Bold-a2c9cd1067f8b328.ttf.woff2"><linkrel="preload"as="font"type="font/woff2"crossoriginhref="../static.files/SourceCodePro-Semibold-d899c5a5c4aeb14a.ttf.woff2"><linkrel="stylesheet"href="../static.files/normalize-76eba96aa4d2e634.css"><linkrel="stylesheet"href="../static.files/rustdoc-cb6f1f67f1bcd037.css"id="mainThemeStyle"><metaname="rustdoc-vars"data-root-path="../"data-static-root-path="../static.files/"data-current-crate="critical_section"data-themes=""data-resource-suffix=""data-rustdoc-version="1.73.0-nightly (8131b9774 2023-08-02)"data-channel="nightly"data-search-js="search-6dfdfced5eff6596.js"data-settings-js="settings-de11bff964e9d4e5.js"data-settings-css="settings-8c76f75bfb6bd192.css"data-theme-light-css="light-6d2c9675f3d09c26.css"data-theme-dark-css="dark-45ceb8f2e522f4d1.css"data-theme-ayu-css="ayu-fd19013d6ce078bf.css"><scriptsrc="../static.files/storage-db41da1a38ea3cb8.js"></script><scriptdefersrc="sidebar-items.js"></script><scriptdefersrc="../static.files/main-0795b7d26be81095.js"></script><noscript><linkrel="stylesheet"media="(prefers-color-scheme:light)"href="../static.files/light-6d2c9675f3d09c26.css"><linkrel="stylesheet"media="(prefers-color-scheme:dark)"href="../static.files/dark-45ceb8f2e522f4d1.css"><linkrel="stylesheet"href="../static.files/noscript-cffde32267a19fd6.css"></noscript><linkrel="alternate icon"type="image/png"href="../static.files/favicon-16x16-8b506e7a72182f1c.png"><linkrel="alternate icon"type="image/png"href="../static.files/favicon-32x32-422f7d1d52889060.png"><linkrel="icon"type="image/svg+xml"href="../static.files/favicon-2c020d218678b618.svg"></head><bodyclass="rustdoc struct"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><navclass="mobile-topbar"><buttonclass="sidebar-menu-toggle">☰</button><aclass="logo-container"href="../critical_section/index.html"><imgclass="rust-logo"src="../static.files/rust-logo-151179464ae7ed46.svg"alt="logo"></a><h2></h2></nav><navclass="sidebar"><aclass="logo-container"href="../critical_section/index.html"><imgclass="rust-logo"src="../static.files/rust-logo-151179464ae7ed46.svg"alt="logo"></a><h2class="location"><ahref="#">Mutex</a></h2><divclass="sidebar-elems"><section><h3><ahref="#implementations">Methods</a></h3><ulclass="block"><li><ahref="#method.borrow">borrow</a></li><li><ahref="#method.borrow_ref">borrow_ref</a></li><li><ahref="#method.borrow_ref_mut">borrow_ref_mut</a></li><li><ahref="#method.get_mut">get_mut</a></li><li><ahref="#method.into_inner">into_inner</a></li><li><ahref="#method.new">new</a></li><li><ahref="#method.replace">replace</a></li><li><ahref="#method.replace_with">replace_with</a></li><li><ahref="#method.take">take</a></li></ul><h3><ahref="#trait-implementations">Trait Implementations</a></h3><ulclass="block"><li><ahref="#impl-Debug-for-Mutex%3CT%3E">Debug</a></li><li><ahref="#impl-Sync-for-Mutex%3CT%3E">Sync</a></li></ul><h3><ahref="#synthetic-implementations">Auto Trait Implementations</a></h3><ulclass="block"><li><ahref="#impl-RefUnwindSafe-for-Mutex%3CT%3E">!RefUnwindS
<p><ahref="https://doc.rust-lang.org/std/sync/struct.Mutex.html"><code>std::sync::Mutex</code></a> has two purposes. It converts types that are [<code>Send</code>]
but not [<code>Sync</code>] into types that are both; and it provides
<ahref="https://doc.rust-lang.org/reference/interior-mutability.html">interior mutability</a>. <code>critical_section::Mutex</code>, on the other hand, only adds
<code>Sync</code>. It does <em>not</em> provide interior mutability.</p>
<p>This was a conscious design choice. It is possible to create multiple
<ahref="struct.CriticalSection.html"title="struct critical_section::CriticalSection"><code>CriticalSection</code></a> tokens, either by nesting critical sections or <code>Copy</code>ing
an existing token. As a result, it would not be sound for <ahref="struct.Mutex.html#method.borrow"title="method critical_section::Mutex::borrow"><code>Mutex::borrow</code></a>
to return <code>&mut T</code>, because there would be nothing to prevent calling
<code>borrow</code> multiple times to create aliased <code>&mut T</code> references.</p>
<p>The solution is to include a runtime check to ensure that each resource is
borrowed only once. This is what <code>std::sync::Mutex</code> does. However, this is
a runtime cost that may not be required in all circumstances. For instance,
<code>Mutex<Cell<T>></code> never needs to create <code>&mut T</code> or equivalent.</p>
<p>If <code>&mut T</code> is needed, the simplest solution is to use <code>Mutex<RefCell<T>></code>,
which is the closest analogy to <code>std::sync::Mutex</code>. [<code>RefCell</code>] inserts the
exact runtime check necessary to guarantee that the <code>&mut T</code> reference is
unique.</p>
<p>To reduce verbosity when using <code>Mutex<RefCell<T>></code>, we reimplement some of
<code>RefCell</code>’s methods on it directly.</p>
</div></details><h2id="implementations"class="small-section-header">Implementations<ahref="#implementations"class="anchor">§</a></h2><divid="implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Mutex%3CT%3E"class="impl"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#78-109">source</a><ahref="#impl-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T><aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.new"class="method"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#81-85">source</a><h4class="code-header">pub const fn <ahref="#method.new"class="fn">new</a>(value: T) -> Self</h4></section></summary><divclass="docblock"><p>Creates a new mutex.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.get_mut"class="method"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#94-96">source</a><h4class="code-header">pub fn <ahref="#method.get_mut"class="fn">get_mut</a>(&mut self) ->&mut T</h4></section></summary><divclass="docblock"><p>Gets a mutable reference to the contained value when the mutex is already uniquely borrowed.</p>
<p>This does not require locking or a critical section since it takes <code>&mut self</code>, which
guarantees unique ownership already. Care must be taken when using this method to
<strong>unsafely</strong> access <code>static mut</code> variables, appropriate fences must be used to prevent
unwanted optimizations.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.into_inner"class="method"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#100-102">source</a><h4class="code-header">pub fn <ahref="#method.into_inner"class="fn">into_inner</a>(self) -> T</h4></section></summary><divclass="docblock"><p>Unwraps the contained value, consuming the mutex.</p>
</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.borrow"class="method"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#106-108">source</a><h4class="code-header">pub fn <ahref="#method.borrow"class="fn">borrow</a><'cs>(&'cs self, _cs: <aclass="struct"href="struct.CriticalSection.html"title="struct critical_section::CriticalSection">CriticalSection</a><'cs>) ->&'cs T</h4></section></summary><divclass="docblock"><p>Borrows the data for the duration of the critical section.</p>
</div></details></div></details><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Mutex%3CRefCell%3CT%3E%3E"class="impl"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#111-170">source</a><ahref="#impl-Mutex%3CRefCell%3CT%3E%3E"class="anchor">§</a><h3class="code-header">impl<T><aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><RefCell<T>></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.replace"class="method"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#122-124">source</a><h4class="code-header">pub fn <ahref="#method.replace"class="fn">replace</a><'cs>(&'cs self, cs: <aclass="struct"href="struct.CriticalSection.html"title="struct critical_section::CriticalSection">CriticalSection</a><'cs>, t: T) -> T</h4></section></summary><divclass="docblock"><p>Borrow the data and call [<code>RefCell::replace</code>]</p>
<p>This is equivalent to <code>self.borrow(cs).replace(t)</code></p>
<h5id="panics"><ahref="#panics">Panics</a></h5>
<p>This call could panic. See the documentation for [<code>RefCell::replace</code>]
F: FnOnce(&mut T) -> T,</span></h4></section></summary><divclass="docblock"><p>Borrow the data and call [<code>RefCell::replace_with</code>]</p>
<p>This is equivalent to <code>self.borrow(cs).replace_with(f)</code></p>
<p>This call could panic. See the documentation for [<code>RefCell::take</code>]
for more details.</p>
</div></details></div></details></div><h2id="trait-implementations"class="small-section-header">Trait Implementations<ahref="#trait-implementations"class="anchor">§</a></h2><divid="trait-implementations-list"><detailsclass="toggle implementors-toggle"open><summary><sectionid="impl-Debug-for-Mutex%3CT%3E"class="impl"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#73">source</a><ahref="#impl-Debug-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T: Debug> Debug for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.fmt"class="method trait-impl"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#73">source</a><ahref="#method.fmt"class="anchor">§</a><h4class="code-header">fn <aclass="fn">fmt</a>(&self, f: &mut Formatter<'_>) -> Result</h4></section></summary><divclass='docblock'>Formats the value using the given formatter. <a>Read more</a></div></details></div></details><sectionid="impl-Sync-for-Mutex%3CT%3E"class="impl"><aclass="src rightside"href="../src/critical_section/mutex.rs.html#191">source</a><ahref="#impl-Sync-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> Sync for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T><spanclass="where fmt-newline">where
T: Send,</span></h3></section></div><h2id="synthetic-implementations"class="small-section-header">Auto Trait Implementations<ahref="#synthetic-implementations"class="anchor">§</a></h2><divid="synthetic-implementations-list"><sectionid="impl-RefUnwindSafe-for-Mutex%3CT%3E"class="impl"><ahref="#impl-RefUnwindSafe-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> !RefUnwindSafe for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T></h3></section><sectionid="impl-Send-for-Mutex%3CT%3E"class="impl"><ahref="#impl-Send-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> Send for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T><spanclass="where fmt-newline">where
T: Send,</span></h3></section><sectionid="impl-Unpin-for-Mutex%3CT%3E"class="impl"><ahref="#impl-Unpin-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> Unpin for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T><spanclass="where fmt-newline">where
T: Unpin,</span></h3></section><sectionid="impl-UnwindSafe-for-Mutex%3CT%3E"class="impl"><ahref="#impl-UnwindSafe-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> UnwindSafe for <aclass="struct"href="struct.Mutex.html"title="struct critical_section::Mutex">Mutex</a><T><spanclass="where fmt-newline">where
T: UnwindSafe,</span></h3></section></div><h2id="blanket-implementations"class="small-section-header">Blanket Implementations<ahref="#blanket-implementations"class="anchor">§</a></h2><divid="blanket-implementations-list"><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-Any-for-Mutex%3CT%3E"class="impl"><ahref="#impl-Any-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> Any for T<spanclass="where fmt-newline">where
T: 'static + ?Sized,</span></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.type_id"class="method trait-impl"><ahref="#method.type_id"class="anchor">§</a><h4class="code-header">fn <aclass="fn">type_id</a>(&self) -> TypeId</h4></section></summary><divclass='docblock'>Gets the <code>TypeId</code> of <code>self</code>. <a>Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-Borrow%3CT%3E-for-Mutex%3CT%3E"class="impl"><ahref="#impl-Borrow%3CT%3E-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> Borrow<T> for T<spanclass="where fmt-newline">where
T: ?Sized,</span></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.borrow-1"class="method trait-impl"><ahref="#method.borrow-1"class="anchor">§</a><h4class="code-header">fn <aclass="fn">borrow</a>(&self) ->&T</h4></section></summary><divclass='docblock'>Immutably borrows from an owned value. <a>Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-BorrowMut%3CT%3E-for-Mutex%3CT%3E"class="impl"><ahref="#impl-BorrowMut%3CT%3E-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> BorrowMut<T> for T<spanclass="where fmt-newline">where
T: ?Sized,</span></h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.borrow_mut"class="method trait-impl"><ahref="#method.borrow_mut"class="anchor">§</a><h4class="code-header">fn <aclass="fn">borrow_mut</a>(&mut self) ->&mut T</h4></section></summary><divclass='docblock'>Mutably borrows from an owned value. <a>Read more</a></div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-From%3CT%3E-for-Mutex%3CT%3E"class="impl"><ahref="#impl-From%3CT%3E-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T> From<T> for T</h3></section></summary><divclass="impl-items"><detailsclass="toggle method-toggle"open><summary><sectionid="method.from"class="method trait-impl"><ahref="#method.from"class="anchor">§</a><h4class="code-header">fn <aclass="fn">from</a>(t: T) -> T</h4></section></summary><divclass="docblock"><p>Returns the argument unchanged.</p>
</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-Into%3CU%3E-for-Mutex%3CT%3E"class="impl"><ahref="#impl-Into%3CU%3E-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T, U> Into<U> for T<spanclass="where fmt-newline">where
U: Into<T>,</span></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error-1"class="associatedtype trait-impl"><ahref="#associatedtype.Error-1"class="anchor">§</a><h4class="code-header">type <aclass="associatedtype">Error</a> = Infallible</h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_from"class="method trait-impl"><ahref="#method.try_from"class="anchor">§</a><h4class="code-header">fn <aclass="fn">try_from</a>(value: U) -> Result<T, <T as TryFrom<U>>::Error></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details><detailsclass="toggle implementors-toggle"><summary><sectionid="impl-TryInto%3CU%3E-for-Mutex%3CT%3E"class="impl"><ahref="#impl-TryInto%3CU%3E-for-Mutex%3CT%3E"class="anchor">§</a><h3class="code-header">impl<T, U> TryInto<U> for T<spanclass="where fmt-newline">where
U: TryFrom<T>,</span></h3></section></summary><divclass="impl-items"><detailsclass="toggle"open><summary><sectionid="associatedtype.Error"class="associatedtype trait-impl"><ahref="#associatedtype.Error"class="anchor">§</a><h4class="code-header">type <aclass="associatedtype">Error</a> = <U as TryFrom<T>>::Error</h4></section></summary><divclass='docblock'>The type returned in the event of a conversion error.</div></details><detailsclass="toggle method-toggle"open><summary><sectionid="method.try_into"class="method trait-impl"><ahref="#method.try_into"class="anchor">§</a><h4class="code-header">fn <aclass="fn">try_into</a>(self) -> Result<U, <U as TryFrom<T>>::Error></h4></section></summary><divclass='docblock'>Performs the conversion.</div></details></div></details></div></section></div></main></body></html>
