mentat/crossbeam_epoch/index.html
2018-08-22 17:04:13 +00:00

278 lines
No EOL
14 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="API documentation for the Rust `crossbeam_epoch` crate.">
<meta name="keywords" content="rust, rustlang, rust-lang, crossbeam_epoch">
<title>crossbeam_epoch - 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="../main.css" id="themeStyle">
<script src="../storage.js"></script>
</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">&#9776;</div>
<p class='location'>Crate crossbeam_epoch</p><div class="sidebar-elems"><div class="block items"><ul><li><a href="#structs">Structs</a></li><li><a href="#traits">Traits</a></li><li><a href="#functions">Functions</a></li></ul></div><p class='location'></p><script>window.sidebarCurrent = {name: 'crossbeam_epoch', ty: 'mod', relpath: '../'};</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">
</div>
</form>
</nav>
<section id='main' class="content">
<h1 class='fqn'><span class='in-band'>Crate <a class="mod" href=''>crossbeam_epoch</a></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/crossbeam_epoch/lib.rs.html#1-104' title='goto source code'>[src]</a></span></h1>
<div class='docblock'><p>Epoch-based memory reclamation.</p>
<p>An interesting problem concurrent collections deal with comes from the remove operation.
Suppose that a thread removes an element from a lock-free map, while another thread is reading
that same element at the same time. The first thread must wait until the second thread stops
reading the element. Only then it is safe to destruct it.</p>
<p>Programming languages that come with garbage collectors solve this problem trivially. The
garbage collector will destruct the removed element when no thread can hold a reference to it
anymore.</p>
<p>This crate implements a basic memory reclamation mechanism, which is based on epochs. When an
element gets removed from a concurrent collection, it is inserted into a pile of garbage and
marked with the current epoch. Every time a thread accesses a collection, it checks the current
epoch, attempts to increment it, and destructs some garbage that became so old that no thread
can be referencing it anymore.</p>
<p>That is the general mechanism behind epoch-based memory reclamation, but the details are a bit
more complicated. Anyhow, memory reclamation is designed to be fully automatic and something
users of concurrent collections don't have to worry much about.</p>
<h1 id="pointers" class="section-header"><a href="#pointers">Pointers</a></h1>
<p>Concurrent collections are built using atomic pointers. This module provides <a href="struct.Atomic.html"><code>Atomic</code></a>, which
is just a shared atomic pointer to a heap-allocated object. Loading an <a href="struct.Atomic.html"><code>Atomic</code></a> yields a
<a href="struct.Shared.html"><code>Shared</code></a>, which is an epoch-protected pointer through which the loaded object can be safely
read.</p>
<h1 id="pinning" class="section-header"><a href="#pinning">Pinning</a></h1>
<p>Before an <a href="struct.Atomic.html"><code>Atomic</code></a> can be loaded, a participant must be <a href="fn.pin.html"><code>pin</code></a>ned. By pinning a participant
we declare that any object that gets removed from now on must not be destructed just
yet. Garbage collection of newly removed objects is suspended until the participant gets
unpinned.</p>
<h1 id="garbage" class="section-header"><a href="#garbage">Garbage</a></h1>
<p>Objects that get removed from concurrent collections must be stashed away until all currently
pinned participants get unpinned. Such objects can be stored into a thread-local or global
storage, where they are kept until the right time for their destruction comes.</p>
<p>There is a global shared instance of garbage queue. You can <a href="fn.defer.html"><code>defer</code></a> the execution of an
arbitrary function until the global epoch is advanced enough. Most notably, concurrent data
structures may defer the deallocation of an object.</p>
<h1 id="apis" class="section-header"><a href="#apis">APIs</a></h1>
<p>For majority of use cases, just use the default garbage collector by invoking <a href="fn.pin.html"><code>pin</code></a>. If you
want to create your own garbage collector, use the <a href="struct.Collector.html"><code>Collector</code></a> API.</p>
</div><h2 id='structs' class='section-header'><a href="#structs">Structs</a></h2>
<table>
<tr class=' module-item'>
<td><a class="struct" href="struct.Atomic.html"
title='struct crossbeam_epoch::Atomic'>Atomic</a></td>
<td class='docblock-short'>
<p>An atomic pointer that can be safely shared between threads.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Collector.html"
title='struct crossbeam_epoch::Collector'>Collector</a></td>
<td class='docblock-short'>
<p>An epoch-based garbage collector.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.CompareAndSetError.html"
title='struct crossbeam_epoch::CompareAndSetError'>CompareAndSetError</a></td>
<td class='docblock-short'>
<p>The error returned on failed compare-and-set operation.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Guard.html"
title='struct crossbeam_epoch::Guard'>Guard</a></td>
<td class='docblock-short'>
<p>A guard that keeps the current thread pinned.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Handle.html"
title='struct crossbeam_epoch::Handle'>Handle</a></td>
<td class='docblock-short'>
<p>A handle to a garbage collector.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Owned.html"
title='struct crossbeam_epoch::Owned'>Owned</a></td>
<td class='docblock-short'>
<p>An owned heap-allocated object.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="struct" href="struct.Shared.html"
title='struct crossbeam_epoch::Shared'>Shared</a></td>
<td class='docblock-short'>
<p>A pointer to an object protected by the epoch GC.</p>
</td>
</tr></table><h2 id='traits' class='section-header'><a href="#traits">Traits</a></h2>
<table>
<tr class=' module-item'>
<td><a class="trait" href="trait.CompareAndSetOrdering.html"
title='trait crossbeam_epoch::CompareAndSetOrdering'>CompareAndSetOrdering</a></td>
<td class='docblock-short'>
<p>Memory orderings for compare-and-set operations.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="trait" href="trait.Pointer.html"
title='trait crossbeam_epoch::Pointer'>Pointer</a></td>
<td class='docblock-short'>
<p>A trait for either <code>Owned</code> or <code>Shared</code> pointers.</p>
</td>
</tr></table><h2 id='functions' class='section-header'><a href="#functions">Functions</a></h2>
<table>
<tr class=' module-item'>
<td><a class="fn" href="fn.default_collector.html"
title='fn crossbeam_epoch::default_collector'>default_collector</a></td>
<td class='docblock-short'>
<p>Returns the default handle associated with the current thread.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.default_handle.html"
title='fn crossbeam_epoch::default_handle'>default_handle</a></td>
<td class='docblock-short'>
<p>Returns the default handle associated with the current thread.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.is_pinned.html"
title='fn crossbeam_epoch::is_pinned'>is_pinned</a></td>
<td class='docblock-short'>
<p>Returns <code>true</code> if the current thread is pinned.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.pin.html"
title='fn crossbeam_epoch::pin'>pin</a></td>
<td class='docblock-short'>
<p>Pins the current thread.</p>
</td>
</tr>
<tr class=' module-item'>
<td><a class="fn" href="fn.unprotected.html"
title='fn crossbeam_epoch::unprotected'>unprotected</a><a title='unsafe function' href='#'><sup></sup></a></td>
<td class='docblock-short'>
<p>Returns a reference to a dummy guard that allows unprotected access to <a href="struct.Atomic.html"><code>Atomic</code></a>s.</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>&#9166;</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>
</div>
</div>
</aside>
<script>
window.rootPath = "../";
window.currentCrate = "crossbeam_epoch";
</script>
<script src="../main.js"></script>
<script defer src="../search-index.js"></script>
</body>
</html>