itsscb/heapless
1
0
Fork 0
mirror of https://github.com/rust-embedded/heapless.git synced 2025-09-27 12:30:35 +00:00
Code Issues Packages Projects Releases Wiki Activity
heapless/spin/index.html

92 lines
13 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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="This crate provides spin-based versions of the primitives in `std::sync` and `std::lazy`. Because synchronization is done through spinning, the primitives are suitable for use in `no_std` environments."><meta name="keywords" content="rust, rustlang, rust-lang, spin"><title>spin - 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="../light.css" id="themeStyle"><link rel="stylesheet" type="text/css" href="../dark.css" disabled ><link rel="stylesheet" type="text/css" href="../ayu.css" disabled ><script id="default-settings" ></script><script src="../storage.js"></script><script src="../crates.js"></script><noscript><link rel="stylesheet" href="../noscript.css"></noscript><link rel="alternate icon" type="image/png" href="../favicon-16x16.png"><link rel="alternate icon" type="image/png" href="../favicon-32x32.png"><link rel="icon" type="image/svg+xml" href="../favicon.svg"><style type="text/css">#crate-search{background-image:url("../down-arrow.svg");}</style></head><body class="rustdoc mod crate"><!--[if lte IE 11]><div class="warning">This old browser is unsupported and will most likely display funky things.</div><![endif]--><nav class="sidebar"><div class="sidebar-menu" role="button">&#9776;</div><a href='../spin/index.html'><div class='logo-container rust-logo'><img src='../rust-logo.png' alt='logo'></div></a><h2 class="location">Crate spin</h2><div class="block version"><div class="narrow-helper"></div><p>Version 0.9.2</p></div><div class="sidebar-elems"><a id="all-types" href="all.html"><p>See all spin's items</p></a><div class="block items"><ul><li><a href="#modules">Modules</a></li><li><a href="#types">Type Definitions</a></li></ul></div><div id="sidebar-vars" data-name="spin" data-ty="mod" data-relpath=""></div><script defer src="sidebar-items.js"></script></div></nav><div class="theme-picker"><button id="theme-picker" aria-label="Pick another theme!" aria-haspopup="menu" title="themes"><img width="18" height="18" alt="Pick another theme!" src="../brush.svg"></button><div id="theme-choices" role="menu"></div></div><nav class="sub"><form class="search-form"><div class="search-container"><div><select id="crate-search"><option value="All crates">All crates</option></select><input class="search-input" name="search" disabled autocomplete="off" spellcheck="false" placeholder="Click or press ‘S’ to search, ‘?’ for more options…" type="search"></div><button type="button" id="help-button" title="help">?</button><a id="settings-menu" href="../settings.html" title="settings"><img width="18" height="18" alt="Change settings" src="../wheel.svg"></a></div></form></nav><section id="main" class="content"><h1 class="fqn"><span class="in-band">Crate <a class="mod" href="#">spin</a><button id="copy-path" onclick="copy_path(this)" title="Copy item path to clipboard"><img src="../clipboard.svg" width="19" height="18" alt="Copy item path"></button></span><span class="out-of-band"><span id="render-detail"><a id="toggle-all-docs" href="javascript:void(0)" title="collapse all docs">[<span class="inner">&#x2212;</span>]</a></span><a class="srclink" href="../src/spin/lib.rs.html#1-186" title="goto source code">[src]</a></span></h1><details class="rustdoc-toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><p>This crate provides <a href="https://en.wikipedia.org/wiki/Spinlock">spin-based</a> versions of the
primitives in <code>std::sync</code> and <code>std::lazy</code>. Because synchronization is done through spinning,
the primitives are suitable for use in <code>no_std</code> environments.</p>
<h2 id="features" class="section-header"><a href="#features">Features</a></h2>
<ul>
<li>
<p><code>Mutex</code>, <code>RwLock</code>, <code>Once</code>/<code>SyncOnceCell</code>, and <code>SyncLazy</code> equivalents</p>
</li>
<li>
<p>Support for <code>no_std</code> environments</p>
</li>
<li>
<p><a href="https://crates.io/crates/lock_api"><code>lock_api</code></a> compatibility</p>
</li>
<li>
<p>Upgradeable <code>RwLock</code> guards</p>
</li>
<li>
<p>Guards can be sent and shared between threads</p>
</li>
<li>
<p>Guard leaking</p>
</li>
<li>
<p>Ticket locks</p>
</li>
<li>
<p>Different strategies for dealing with contention</p>
</li>
</ul>
<h2 id="relationship-with-stdsync" class="section-header"><a href="#relationship-with-stdsync">Relationship with <code>std::sync</code></a></h2>
<p>While <code>spin</code> is not a drop-in replacement for <code>std::sync</code> (and
<a href="https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html">should not be considered as such</a>)
an effort is made to keep this crate reasonably consistent with <code>std::sync</code>.</p>
<p>Many of the types defined in this crate have ‘additional capabilities’ when compared to <code>std::sync</code>:</p>
<ul>
<li>
<p>Because spinning does not depend on the thread-driven model of <code>std::sync</code>, guards (<a href="mutex/struct.MutexGuard.html" title="MutexGuard"><code>MutexGuard</code></a>,
<a href="rwlock/struct.RwLockReadGuard.html" title="RwLockReadGuard"><code>RwLockReadGuard</code></a>, <a href="type.RwLockWriteGuard.html" title="RwLockWriteGuard"><code>RwLockWriteGuard</code></a>, etc.) may be sent and shared between threads.</p>
</li>
<li>
<p><a href="type.RwLockUpgradableGuard.html" title="RwLockUpgradableGuard"><code>RwLockUpgradableGuard</code></a> supports being upgraded into a <a href="type.RwLockWriteGuard.html" title="RwLockWriteGuard"><code>RwLockWriteGuard</code></a>.</p>
</li>
<li>
<p>Guards support <a href="https://doc.rust-lang.org/nomicon/leaking.html">leaking</a>.</p>
</li>
<li>
<p><a href="type.Once.html" title="Once"><code>Once</code></a> owns the value returned by its <code>call_once</code> initializer.</p>
</li>
<li>
<p><a href="type.RwLock.html" title="RwLock"><code>RwLock</code></a> supports counting readers and writers.</p>
</li>
</ul>
<p>Conversely, the types in this crate do not have some of the features <code>std::sync</code> has:</p>
<ul>
<li>Locks do not track <a href="https://doc.rust-lang.org/nomicon/poisoning.html">panic poisoning</a>.</li>
</ul>
<h3 id="feature-flags" class="section-header"><a href="#feature-flags">Feature flags</a></h3>
<p>The crate comes with a few feature flags that you may wish to use.</p>
<ul>
<li>
<p><code>lock_api</code> enables support for <a href="https://crates.io/crates/lock_api"><code>lock_api</code></a></p>
</li>
<li>
<p><code>ticket_mutex</code> uses a ticket lock for the implementation of <code>Mutex</code></p>
</li>
<li>
<p><code>std</code> enables support for thread yielding instead of spinning</p>
</li>
</ul>
</div></details><h2 id="reexports" class="section-header"><a href="#reexports">Re-exports</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left import-item"><code>pub use mutex::<a class="struct" href="mutex/struct.MutexGuard.html" title="struct spin::mutex::MutexGuard">MutexGuard</a>;</code></div><div class="item-right docblock-short"></div></div><div class="item-row"><div class="item-left import-item"><code>pub use rwlock::<a class="struct" href="rwlock/struct.RwLockReadGuard.html" title="struct spin::rwlock::RwLockReadGuard">RwLockReadGuard</a>;</code></div><div class="item-right docblock-short"></div></div><div class="item-row"><div class="item-left import-item"><code>pub use relax::<a class="struct" href="relax/struct.Spin.html" title="struct spin::relax::Spin">Spin</a>;</code></div><div class="item-right docblock-short"></div></div><div class="item-row"><div class="item-left import-item"><code>pub use relax::<a class="trait" href="relax/trait.RelaxStrategy.html" title="trait spin::relax::RelaxStrategy">RelaxStrategy</a>;</code></div><div class="item-right docblock-short"></div></div></div><h2 id="modules" class="section-header"><a href="#modules">Modules</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="mod" href="barrier/index.html" title="spin::barrier mod">barrier</a></div><div class="item-right docblock-short"><p>Synchronization primitive allowing multiple threads to synchronize the
beginning of some computation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="lazy/index.html" title="spin::lazy mod">lazy</a></div><div class="item-right docblock-short"><p>Synchronization primitives for lazy evaluation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="lock_api/index.html" title="spin::lock_api mod">lock_api</a></div><div class="item-right docblock-short"><p>Spin synchronisation primitives, but compatible with <a href="https://crates.io/crates/lock_api"><code>lock_api</code></a>.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="mutex/index.html" title="spin::mutex mod">mutex</a></div><div class="item-right docblock-short"><p>Locks that have the same behaviour as a mutex.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="once/index.html" title="spin::once mod">once</a></div><div class="item-right docblock-short"><p>Synchronization primitives for one-time evaluation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="relax/index.html" title="spin::relax mod">relax</a></div><div class="item-right docblock-short"><p>Strategies that determine the behaviour of locks when encountering contention.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="mod" href="rwlock/index.html" title="spin::rwlock mod">rwlock</a></div><div class="item-right docblock-short"><p>A lock that provides data access to either one writer or many readers.</p>
</div></div></div><h2 id="types" class="section-header"><a href="#types">Type Definitions</a></h2>
<div class="item-table"><div class="item-row"><div class="item-left module-item"><a class="type" href="type.Barrier.html" title="spin::Barrier type">Barrier</a></div><div class="item-right docblock-short"><p>A primitive that synchronizes the execution of multiple threads. See <a href="barrier/struct.Barrier.html" title="barrier::Barrier"><code>barrier::Barrier</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.Lazy.html" title="spin::Lazy type">Lazy</a></div><div class="item-right docblock-short"><p>A value which is initialized on the first access. See <a href="lazy/struct.Lazy.html" title="lazy::Lazy"><code>lazy::Lazy</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.Mutex.html" title="spin::Mutex type">Mutex</a></div><div class="item-right docblock-short"><p>A primitive that synchronizes the execution of multiple threads. See <a href="mutex/struct.Mutex.html" title="mutex::Mutex"><code>mutex::Mutex</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.Once.html" title="spin::Once type">Once</a></div><div class="item-right docblock-short"><p>A primitive that provides lazy one-time initialization. See <a href="once/struct.Once.html" title="once::Once"><code>once::Once</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.RwLock.html" title="spin::RwLock type">RwLock</a></div><div class="item-right docblock-short"><p>A lock that provides data access to either one writer or many readers. See <a href="rwlock/struct.RwLock.html" title="rwlock::RwLock"><code>rwlock::RwLock</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.RwLockUpgradableGuard.html" title="spin::RwLockUpgradableGuard type">RwLockUpgradableGuard</a></div><div class="item-right docblock-short"><p>A guard that provides immutable data access but can be upgraded to <a href="type.RwLockWriteGuard.html" title="RwLockWriteGuard"><code>RwLockWriteGuard</code></a>. See
<a href="rwlock/struct.RwLockUpgradableGuard.html" title="rwlock::RwLockUpgradableGuard"><code>rwlock::RwLockUpgradableGuard</code></a> for documentation.</p>
</div></div><div class="item-row"><div class="item-left module-item"><a class="type" href="type.RwLockWriteGuard.html" title="spin::RwLockWriteGuard type">RwLockWriteGuard</a></div><div class="item-right docblock-short"><p>A guard that provides mutable data access. See <a href="rwlock/struct.RwLockWriteGuard.html" title="rwlock::RwLockWriteGuard"><code>rwlock::RwLockWriteGuard</code></a> for documentation.</p>
</div></div></div></section><section id="search" class="content hidden"></section><div id="rustdoc-vars" data-root-path="../" data-current-crate="spin" data-search-index-js="../search-index.js" data-search-js="../search.js"></div>
<script src="../main.js"></script>
</body></html>
Reference in New Issue View Git Blame Copy Permalink