38 lines
10 KiB
HTML
38 lines
10 KiB
HTML
<!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="`offset-allocator`"><title>offset_allocator - Rust</title><script>if(window.location.protocol!=="file:")document.head.insertAdjacentHTML("beforeend","SourceSerif4-Regular-6b053e98.ttf.woff2,FiraSans-Regular-0fe48ade.woff2,FiraSans-Medium-e1aa3f0a.woff2,SourceCodePro-Regular-8badfe75.ttf.woff2,SourceCodePro-Semibold-aa29a496.ttf.woff2".split(",").map(f=>`<link rel="preload" as="font" type="font/woff2" crossorigin href="../static.files/${f}">`).join(""))</script><link rel="stylesheet" href="../static.files/normalize-9960930a.css"><link rel="stylesheet" href="../static.files/rustdoc-42caa33d.css"><meta name="rustdoc-vars" data-root-path="../" data-static-root-path="../static.files/" data-current-crate="offset_allocator" data-themes="" data-resource-suffix="" data-rustdoc-version="1.84.0 (9fc6b4312 2025-01-07)" data-channel="1.84.0" data-search-js="search-92e6798f.js" data-settings-js="settings-0f613d39.js" ><script src="../static.files/storage-59e33391.js"></script><script defer src="../crates.js"></script><script defer src="../static.files/main-5f194d8c.js"></script><noscript><link rel="stylesheet" href="../static.files/noscript-893ab5e7.css"></noscript><link rel="alternate icon" type="image/png" href="../static.files/favicon-32x32-6580c154.png"><link rel="icon" type="image/svg+xml" href="../static.files/favicon-044be391.svg"></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="mobile-topbar"><button class="sidebar-menu-toggle" title="show sidebar"></button></nav><nav class="sidebar"><div class="sidebar-crate"><h2><a href="../offset_allocator/index.html">offset_<wbr>allocator</a><span class="version">0.2.0</span></h2></div><div class="sidebar-elems"><ul class="block"><li><a id="all-types" href="all.html">All Items</a></li></ul><section id="rustdoc-toc"><h3><a href="#">Sections</a></h3><ul class="block top-toc"><li><a href="#offset-allocator" title="`offset-allocator`"><code>offset-allocator</code></a><ul><li><a href="#overview" title="Overview">Overview</a></li><li><a href="#description" title="Description">Description</a></li><li><a href="#references" title="References">References</a></li><li><a href="#author" title="Author">Author</a></li><li><a href="#license" title="License">License</a></li><li><a href="#code-of-conduct" title="Code of conduct">Code of conduct</a></li></ul></li></ul><h3><a href="#modules">Crate Items</a></h3><ul class="block"><li><a href="#modules" title="Modules">Modules</a></li><li><a href="#structs" title="Structs">Structs</a></li><li><a href="#traits" title="Traits">Traits</a></li></ul></section><div id="rustdoc-modnav"></div></div></nav><div class="sidebar-resizer"></div><main><div class="width-limiter"><rustdoc-search></rustdoc-search><section id="main-content" class="content"><div class="main-heading"><h1>Crate <span>offset_allocator</span><button id="copy-path" title="Copy item path to clipboard">Copy item path</button></h1><rustdoc-toolbar></rustdoc-toolbar><span class="sub-heading"><a class="src" href="../src/offset_allocator/lib.rs.html#3-592">Source</a> </span></div><details class="toggle top-doc" open><summary class="hideme"><span>Expand description</span></summary><div class="docblock"><h2 id="offset-allocator"><a class="doc-anchor" href="#offset-allocator">§</a><code>offset-allocator</code></h2><h3 id="overview"><a class="doc-anchor" href="#overview">§</a>Overview</h3>
|
||
<p>This is a port of <a href="https://github.com/sebbbi/OffsetAllocator">Sebastian Aaltonen’s <code>OffsetAllocator</code></a> package for C++ to 100% safe Rust. It’s a fast, simple, hard real time allocator. This is especially useful for managing GPU resources, and the goal is to use it in <a href="https://github.com/bevyengine/bevy/">Bevy</a>.</p>
|
||
<p>The port has been made into more or less idiomatic Rust but is otherwise mostly line-for-line, preserving comments. That way, patches for the original <code>OffsetAllocator</code> should be readily transferable to this Rust port.</p>
|
||
<p>Please note that <code>offset-allocator</code> isn’t a Rust allocator conforming to the <code>GlobalAlloc</code> trait. You can’t use this crate as a drop-in replacement for the system allocator, <code>jemalloc</code>, <code>wee_alloc</code>, etc. The general algorithm that this crate uses could be adapted to construct a Rust allocator, but that’s beyond the scope of this particular implementation. This is by design, so that this allocator can be used to manage resources that aren’t just CPU memory: in particular, you can manage allocations inside GPU buffers with it. By contrast, Rust allocators are hard-wired to the CPU and can’t be used to manage GPU resources.</p>
|
||
<h3 id="description"><a class="doc-anchor" href="#description">§</a>Description</h3>
|
||
<p>This allocator is completely agnostic to what it’s allocating: it only knows
|
||
about a contiguous block of memory of a specific size. That size need not be in
|
||
bytes: this is especially useful when allocating inside a buffer of fixed-size
|
||
structures. For example, if using this allocator to divide up a GPU index
|
||
buffer object, one might want to treat the units of allocation as 32-bit
|
||
floats.</p>
|
||
<p>From <a href="https://github.com/sebbbi/OffsetAllocator/blob/main/README.md">the original README</a>:</p>
|
||
<blockquote>
|
||
<p>Fast hard realtime O(1) offset allocator with minimal fragmentation.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>Uses 256 bins with 8 bit floating point distribution (3 bit mantissa + 5 bit exponent) and a two level bitfield to find the next available bin using 2x LZCNT instructions to make all operations O(1). Bin sizes following the floating point distribution ensures hard bounds for memory overhead percentage regarless of size class. Pow2 bins would waste up to +100% memory (+50% on average). Our float bins waste up to +12.5% (+6.25% on average).</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>The allocation metadata is stored in a separate data structure, making this allocator suitable for sub-allocating any resources, such as GPU heaps, buffers and arrays. Returns an offset to the first element of the allocated contiguous range.</p>
|
||
</blockquote>
|
||
<h3 id="references"><a class="doc-anchor" href="#references">§</a>References</h3>
|
||
<p>Again per <a href="https://github.com/sebbbi/OffsetAllocator/blob/main/README.md">the original README</a>:</p>
|
||
<blockquote>
|
||
<p>This allocator is similar to the two-level segregated fit (TLSF) algorithm.</p>
|
||
</blockquote>
|
||
<blockquote>
|
||
<p>Comparison paper shows that TLSF algorithm provides best in class performance and fragmentation: <a href="https://www.researchgate.net/profile/Alfons-Crespo/publication/234785757_A_comparison_of_memory_allocators_for_real-time_applications/links/5421d8550cf2a39f4af765f4/A-comparison-of-memory-allocators-for-real-time-applications.pdf">https://www.researchgate.net/profile/Alfons-Crespo/publication/234785757_A_comparison_of_memory_allocators_for_real-time_applications/links/5421d8550cf2a39f4af765f4/A-comparison-of-memory-allocators-for-real-time-applications.pdf</a></p>
|
||
</blockquote>
|
||
<h3 id="author"><a class="doc-anchor" href="#author">§</a>Author</h3>
|
||
<p>C++ version: Sebastian Aaltonen</p>
|
||
<p>Rust port: Patrick Walton, @pcwalton</p>
|
||
<h3 id="license"><a class="doc-anchor" href="#license">§</a>License</h3>
|
||
<p>Licensed under the MIT license. See <code>LICENSE-MIT</code> for details.</p>
|
||
<h3 id="code-of-conduct"><a class="doc-anchor" href="#code-of-conduct">§</a>Code of conduct</h3>
|
||
<p><code>offset-allocator</code> follows the same code of conduct as Rust itself. Reports can be made to the project authors.</p>
|
||
</div></details><h2 id="modules" class="section-header">Modules<a href="#modules" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="mod" href="ext/index.html" title="mod offset_allocator::ext">ext</a></div><div class="desc docblock-short">Extension functions not present in the original C++ <code>OffsetAllocator</code>.</div></li></ul><h2 id="structs" class="section-header">Structs<a href="#structs" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="struct" href="struct.Allocation.html" title="struct offset_allocator::Allocation">Allocation</a></div><div class="desc docblock-short">A single allocation.</div></li><li><div class="item-name"><a class="struct" href="struct.Allocator.html" title="struct offset_allocator::Allocator">Allocator</a></div><div class="desc docblock-short">An allocator that manages a single contiguous chunk of space and hands out
|
||
portions of it as requested.</div></li><li><div class="item-name"><a class="struct" href="struct.StorageReport.html" title="struct offset_allocator::StorageReport">Storage<wbr>Report</a></div><div class="desc docblock-short">Provides a summary of the state of the allocator, including space remaining.</div></li><li><div class="item-name"><a class="struct" href="struct.StorageReportFull.html" title="struct offset_allocator::StorageReportFull">Storage<wbr>Report<wbr>Full</a></div><div class="desc docblock-short">Provides a detailed accounting of each bin within the allocator.</div></li><li><div class="item-name"><a class="struct" href="struct.StorageReportFullRegion.html" title="struct offset_allocator::StorageReportFullRegion">Storage<wbr>Report<wbr>Full<wbr>Region</a></div><div class="desc docblock-short">A detailed accounting of each allocator bin.</div></li></ul><h2 id="traits" class="section-header">Traits<a href="#traits" class="anchor">§</a></h2><ul class="item-table"><li><div class="item-name"><a class="trait" href="trait.NodeIndex.html" title="trait offset_allocator::NodeIndex">Node<wbr>Index</a></div><div class="desc docblock-short">Determines the number of allocations that the allocator supports.</div></li><li><div class="item-name"><a class="trait" href="trait.NodeIndexNonMax.html" title="trait offset_allocator::NodeIndexNonMax">Node<wbr>Index<wbr>NonMax</a></div><div class="desc docblock-short">The <code>NonMax</code> version of the <a href="trait.NodeIndex.html" title="trait offset_allocator::NodeIndex"><code>NodeIndex</code></a>.</div></li></ul></section></div></main></body></html> |