aaru-dps/libaaruformat
1
0
Fork 0
mirror of https://github.com/aaru-dps/libaaruformat.git synced 2026-02-16 21:23:08 +00:00
Code Issues 3 Packages Projects Releases Wiki Activity
Files
benchmark
libaaruformat/docs/html/static__lru__hash__map_8h.html

606 lines
39 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.15.0"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libaaruformat: include/aaruformat/static_lru_hash_map.h File Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr id="projectrow">
<td id="projectalign">
<div id="projectname">libaaruformat<span id="projectnumber">&#160;1.0</span>
</div>
<div id="projectbrief">Aaru Data Preservation Suite - Format Library</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.15.0 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search/",'.html');
</script>
<script type="text/javascript">
$(function() { codefold.init(); });
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search',true);
$(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(function(){initNavTree('static__lru__hash__map_8h.html','',''); });
</script>
<div id="container">
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>
<div class="header">
<div class="headertitle"><div class="title">static_lru_hash_map.h File Reference</div></div>
</div><!--header-->
<div class="contents">
<p>Static-memory hash map with LRU-like eviction for fixed RAM usage.
<a href="#details">More...</a></p>
<div class="textblock"><code>#include &lt;stdbool.h&gt;</code><br />
<code>#include &lt;stdint.h&gt;</code><br />
<code>#include &lt;stdlib.h&gt;</code><br />
</div>
<p><a href="static__lru__hash__map_8h_source.html">Go to the source code of this file.</a></p>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-nested-classes" class="groupheader"><a id="nested-classes" name="nested-classes"></a>
Data Structures</h2></td></tr>
<tr class="memitem:lru_5Fkv_5Fpair_5Ft" id="r_lru_5Fkv_5Fpair_5Ft"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structlru__kv__pair__t.html">lru_kv_pair_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Single key/value slot with access tracking for the static LRU hash map. <a href="structlru__kv__pair__t.html#details">More...</a><br /></td></tr>
<tr class="memitem:static_5Flru_5Fhash_5Fmap_5Ft" id="r_static_5Flru_5Fhash_5Fmap_5Ft"><td class="memItemLeft" align="right" valign="top">struct &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Fixed-size hash map with LRU-like eviction for bounded memory usage. <a href="structstatic__lru__hash__map__t.html#details">More...</a><br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-define-members" class="groupheader"><a id="define-members" name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:a7a71f318d85bb6078f1a173e6bd73bec" id="r_a7a71f318d85bb6078f1a173e6bd73bec"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a7a71f318d85bb6078f1a173e6bd73bec">STATIC_LRU_EVICTION_LOAD_FACTOR</a>&#160;&#160;&#160;0.90</td></tr>
<tr class="memdesc:a7a71f318d85bb6078f1a173e6bd73bec"><td class="mdescLeft">&#160;</td><td class="mdescRight">Default configuration constants for the static LRU hash map. <br /></td></tr>
<tr class="memitem:a026228d36f32c49efcc1d7994402d92b" id="r_a026228d36f32c49efcc1d7994402d92b"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a026228d36f32c49efcc1d7994402d92b">STATIC_LRU_TARGET_LOAD_FACTOR</a>&#160;&#160;&#160;0.75</td></tr>
<tr class="memdesc:a026228d36f32c49efcc1d7994402d92b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Evict down to 75% capacity. <br /></td></tr>
<tr class="memitem:ad4401262640f8b02ee011d53bc71f2e2" id="r_ad4401262640f8b02ee011d53bc71f2e2"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#ad4401262640f8b02ee011d53bc71f2e2">STATIC_LRU_AGING_INTERVAL</a>&#160;&#160;&#160;100000</td></tr>
<tr class="memdesc:ad4401262640f8b02ee011d53bc71f2e2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Age access counts every N operations. <br /></td></tr>
<tr class="memitem:a4282049031b9dcd0f3c1d4f730e8af58" id="r_a4282049031b9dcd0f3c1d4f730e8af58"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a4282049031b9dcd0f3c1d4f730e8af58">STATIC_LRU_MIN_SIZE</a>&#160;&#160;&#160;1024</td></tr>
<tr class="memdesc:a4282049031b9dcd0f3c1d4f730e8af58"><td class="mdescLeft">&#160;</td><td class="mdescRight">Minimum map size to prevent edge cases. <br /></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 id="header-func-members" class="groupheader"><a id="func-members" name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:a2c6aba784bb6cccf761347ad7c30e865" id="r_a2c6aba784bb6cccf761347ad7c30e865"><td class="memItemLeft" align="right" valign="top"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a2c6aba784bb6cccf761347ad7c30e865">static_lru_create_map</a> (size_t size)</td></tr>
<tr class="memdesc:a2c6aba784bb6cccf761347ad7c30e865"><td class="mdescLeft">&#160;</td><td class="mdescRight">Creates a new static LRU hash map with fixed size. <br /></td></tr>
<tr class="memitem:a0dfd7086461b507c3a0e329e0d047e74" id="r_a0dfd7086461b507c3a0e329e0d047e74"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a0dfd7086461b507c3a0e329e0d047e74">static_lru_free_map</a> (<a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map)</td></tr>
<tr class="memdesc:a0dfd7086461b507c3a0e329e0d047e74"><td class="mdescLeft">&#160;</td><td class="mdescRight">Frees all memory associated with a static LRU hash map. <br /></td></tr>
<tr class="memitem:aa96225bd1e66d8afd7541bc4587bb88f" id="r_aa96225bd1e66d8afd7541bc4587bb88f"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#aa96225bd1e66d8afd7541bc4587bb88f">static_lru_insert_map</a> (<a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map, uint64_t key, uint64_t value)</td></tr>
<tr class="memdesc:aa96225bd1e66d8afd7541bc4587bb88f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Inserts a key-value pair into the static LRU hash map. <br /></td></tr>
<tr class="memitem:a450c1d834b74de014c5e943e662b39c0" id="r_a450c1d834b74de014c5e943e662b39c0"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a450c1d834b74de014c5e943e662b39c0">static_lru_lookup_map</a> (<a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map, uint64_t key, uint64_t *out_value)</td></tr>
<tr class="memdesc:a450c1d834b74de014c5e943e662b39c0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Looks up a value by key in the static LRU hash map. <br /></td></tr>
<tr class="memitem:aead2422ca9f9aa1f4f08c65ba6dd1425" id="r_aead2422ca9f9aa1f4f08c65ba6dd1425"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#aead2422ca9f9aa1f4f08c65ba6dd1425">static_lru_contains_key</a> (const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map, uint64_t key)</td></tr>
<tr class="memdesc:aead2422ca9f9aa1f4f08c65ba6dd1425"><td class="mdescLeft">&#160;</td><td class="mdescRight">Checks if a key exists in the map WITHOUT updating access count. <br /></td></tr>
<tr class="memitem:a3fad20805fcd096bb6f4c9ec7b9e666b" id="r_a3fad20805fcd096bb6f4c9ec7b9e666b"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a3fad20805fcd096bb6f4c9ec7b9e666b">static_lru_evict</a> (<a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map, size_t entries_to_keep)</td></tr>
<tr class="memdesc:a3fad20805fcd096bb6f4c9ec7b9e666b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Manually triggers eviction of least-used entries. <br /></td></tr>
<tr class="memitem:a1682e53b3efd8786a8d0620fa12f142c" id="r_a1682e53b3efd8786a8d0620fa12f142c"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a1682e53b3efd8786a8d0620fa12f142c">static_lru_age_counts</a> (<a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map)</td></tr>
<tr class="memdesc:a1682e53b3efd8786a8d0620fa12f142c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Manually ages all access counts. <br /></td></tr>
<tr class="memitem:a5deee3df8ccae2c0c34bec4c4a28dfa2" id="r_a5deee3df8ccae2c0c34bec4c4a28dfa2"><td class="memItemLeft" align="right" valign="top">double&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a5deee3df8ccae2c0c34bec4c4a28dfa2">static_lru_load_factor</a> (const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map)</td></tr>
<tr class="memdesc:a5deee3df8ccae2c0c34bec4c4a28dfa2"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the current load factor of the map. <br /></td></tr>
<tr class="memitem:a1d284756f5f2f589f20dd0be5a793390" id="r_a1d284756f5f2f589f20dd0be5a793390"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="#a1d284756f5f2f589f20dd0be5a793390">static_lru_free_slots</a> (const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *map)</td></tr>
<tr class="memdesc:a1d284756f5f2f589f20dd0be5a793390"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the number of free slots available. <br /></td></tr>
</table>
<a name="details" id="details"></a><h2 id="header-details" class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Static-memory hash map with LRU-like eviction for fixed RAM usage. </p>
<p>This hash map variant has the following characteristics:</p><ul>
<li>Fixed memory allocation set at creation time (never grows)</li>
<li>Tracks access frequency for each entry</li>
<li>Automatically evicts least-frequently-used entries when approaching capacity</li>
<li>Maintains a minimum percentage of free slots for new insertions</li>
<li>Uses approximate LFU (Least Frequently Used) with aging to prevent stale entries</li>
</ul>
<p>Use this instead of <a class="el" href="structhash__map__t.html" title="Minimal open-addressing hash map for 64-bit key/value pairs used in deduplication lookup.">hash_map_t</a> when you need predictable, bounded memory usage and can tolerate eviction of less-frequently-accessed entries. </p>
<p class="definition">Definition in file <a class="el" href="static__lru__hash__map_8h_source.html">static_lru_hash_map.h</a>.</p>
</div><a name="doc-define-members" id="doc-define-members"></a><h2 id="header-doc-define-members" class="groupheader">Macro Definition Documentation</h2>
<a id="ad4401262640f8b02ee011d53bc71f2e2" name="ad4401262640f8b02ee011d53bc71f2e2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ad4401262640f8b02ee011d53bc71f2e2">&#9670;&#160;</a></span>STATIC_LRU_AGING_INTERVAL</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define STATIC_LRU_AGING_INTERVAL&#160;&#160;&#160;100000</td>
</tr>
</table>
</div><div class="memdoc">
<p>Age access counts every N operations. </p>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8h_source.html#l00055">55</a> of file <a class="el" href="static__lru__hash__map_8h_source.html">static_lru_hash_map.h</a>.</p>
<p class="reference">Referenced by <a class="el" href="static__lru__hash__map_8c_source.html#l00245">static_lru_insert_map()</a>.</p>
</div>
</div>
<a id="a7a71f318d85bb6078f1a173e6bd73bec" name="a7a71f318d85bb6078f1a173e6bd73bec"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a7a71f318d85bb6078f1a173e6bd73bec">&#9670;&#160;</a></span>STATIC_LRU_EVICTION_LOAD_FACTOR</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define STATIC_LRU_EVICTION_LOAD_FACTOR&#160;&#160;&#160;0.90</td>
</tr>
</table>
</div><div class="memdoc">
<p>Default configuration constants for the static LRU hash map. </p>
<p>These can be overridden by defining them before including this header. Trigger eviction when 90% full </p>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8h_source.html#l00047">47</a> of file <a class="el" href="static__lru__hash__map_8h_source.html">static_lru_hash_map.h</a>.</p>
<p class="reference">Referenced by <a class="el" href="static__lru__hash__map_8c_source.html#l00204">static_lru_create_map()</a>.</p>
</div>
</div>
<a id="a4282049031b9dcd0f3c1d4f730e8af58" name="a4282049031b9dcd0f3c1d4f730e8af58"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4282049031b9dcd0f3c1d4f730e8af58">&#9670;&#160;</a></span>STATIC_LRU_MIN_SIZE</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define STATIC_LRU_MIN_SIZE&#160;&#160;&#160;1024</td>
</tr>
</table>
</div><div class="memdoc">
<p>Minimum map size to prevent edge cases. </p>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8h_source.html#l00059">59</a> of file <a class="el" href="static__lru__hash__map_8h_source.html">static_lru_hash_map.h</a>.</p>
<p class="reference">Referenced by <a class="el" href="static__lru__hash__map_8c_source.html#l00204">static_lru_create_map()</a>.</p>
</div>
</div>
<a id="a026228d36f32c49efcc1d7994402d92b" name="a026228d36f32c49efcc1d7994402d92b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a026228d36f32c49efcc1d7994402d92b">&#9670;&#160;</a></span>STATIC_LRU_TARGET_LOAD_FACTOR</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">#define STATIC_LRU_TARGET_LOAD_FACTOR&#160;&#160;&#160;0.75</td>
</tr>
</table>
</div><div class="memdoc">
<p>Evict down to 75% capacity. </p>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8h_source.html#l00051">51</a> of file <a class="el" href="static__lru__hash__map_8h_source.html">static_lru_hash_map.h</a>.</p>
<p class="reference">Referenced by <a class="el" href="static__lru__hash__map_8c_source.html#l00204">static_lru_create_map()</a>.</p>
</div>
</div>
<a name="doc-func-members" id="doc-func-members"></a><h2 id="header-doc-func-members" class="groupheader">Function Documentation</h2>
<a id="a1682e53b3efd8786a8d0620fa12f142c" name="a1682e53b3efd8786a8d0620fa12f142c"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a1682e53b3efd8786a8d0620fa12f142c">&#9670;&#160;</a></span>static_lru_age_counts()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void static_lru_age_counts </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Manually ages all access counts. </p>
<p>Halves all access counts in the map. This is normally done automatically every STATIC_LRU_AGING_INTERVAL operations, but can be called manually to reset frequency tracking.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL. </td></tr>
</table>
</dd>
</dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00331">331</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8c_source.html#l00064">age_access_counts()</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00104">static_lru_hash_map_t::age_counter</a>.</p>
</div>
</div>
<a id="aead2422ca9f9aa1f4f08c65ba6dd1425" name="aead2422ca9f9aa1f4f08c65ba6dd1425"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aead2422ca9f9aa1f4f08c65ba6dd1425">&#9670;&#160;</a></span>static_lru_contains_key()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool static_lru_contains_key </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>key</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Checks if a key exists in the map WITHOUT updating access count. </p>
<p>This is useful when you need to check existence without affecting eviction priority.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map to search. Must not be NULL. </td></tr>
<tr><td class="paramname">key</td><td>The key to search for. Must not be 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns whether the key exists in the map. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">true</td><td>Key exists in the map. </td></tr>
<tr><td class="paramname">false</td><td>Key not found.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>Unlike <a class="el" href="#a450c1d834b74de014c5e943e662b39c0" title="Looks up a value by key in the static LRU hash map.">static_lru_lookup_map()</a>, this does NOT update access_count. </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00314">314</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00073">lru_kv_pair_t::key</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00099">static_lru_hash_map_t::table</a>, and <a class="el" href="static__lru__hash__map_8c_source.html#l00050">TOMBSTONE_KEY</a>.</p>
</div>
</div>
<a id="a2c6aba784bb6cccf761347ad7c30e865" name="a2c6aba784bb6cccf761347ad7c30e865"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2c6aba784bb6cccf761347ad7c30e865">&#9670;&#160;</a></span>static_lru_create_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> * static_lru_create_map </td>
<td>(</td>
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>size</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Creates a new static LRU hash map with fixed size. </p>
<p>Allocates and initializes a new hash map structure with the given size. This is the ONLY allocation that will ever occur for this map - the size is fixed and will never grow. When the map fills up, old entries are evicted instead of allocating more memory.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">size</td><td>Fixed size of the hash table. Enforced minimum is STATIC_LRU_MIN_SIZE. Choose this based on your memory budget and expected working set.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns a pointer to the newly created hash map, or NULL if allocation fails.</dd></dl>
<dl class="section note"><dt>Note</dt><dd>Memory usage: approximately (size * 24) bytes for the table. </dd>
<dd>
The caller is responsible for freeing the returned hash map using <a class="el" href="#a0dfd7086461b507c3a0e329e0d047e74" title="Frees all memory associated with a static LRU hash map.">static_lru_free_map()</a>. </dd>
<dd>
A key value of 0 is reserved to indicate empty slots and cannot be used as a valid key.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a0dfd7086461b507c3a0e329e0d047e74" title="Frees all memory associated with a static LRU hash map.">static_lru_free_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00204">204</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00105">static_lru_hash_map_t::_padding</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00104">static_lru_hash_map_t::age_counter</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00101">static_lru_hash_map_t::count</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00102">static_lru_hash_map_t::max_count</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00047">STATIC_LRU_EVICTION_LOAD_FACTOR</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00059">STATIC_LRU_MIN_SIZE</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00051">STATIC_LRU_TARGET_LOAD_FACTOR</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00099">static_lru_hash_map_t::table</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00103">static_lru_hash_map_t::target_count</a>.</p>
</div>
</div>
<a id="a3fad20805fcd096bb6f4c9ec7b9e666b" name="a3fad20805fcd096bb6f4c9ec7b9e666b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a3fad20805fcd096bb6f4c9ec7b9e666b">&#9670;&#160;</a></span>static_lru_evict()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">size_t static_lru_evict </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t</td> <td class="paramname"><span class="paramname"><em>entries_to_keep</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Manually triggers eviction of least-used entries. </p>
<p>Forces an eviction cycle even if the map hasn't reached the eviction threshold. Useful for proactively freeing memory or resetting the cache.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL. </td></tr>
<tr><td class="paramname">entries_to_keep</td><td>Number of entries to keep after eviction. If 0, uses target_count.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Number of entries actually evicted. </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00328">328</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8c_source.html#l00139">evict_lru_entries()</a>.</p>
</div>
</div>
<a id="a0dfd7086461b507c3a0e329e0d047e74" name="a0dfd7086461b507c3a0e329e0d047e74"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a0dfd7086461b507c3a0e329e0d047e74">&#9670;&#160;</a></span>static_lru_free_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void static_lru_free_map </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Frees all memory associated with a static LRU hash map. </p>
<p>Deallocates the hash table and the hash map structure itself.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map to free. Can be NULL (no operation performed).</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>This function does not free any memory pointed to by the values stored in the map.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a2c6aba784bb6cccf761347ad7c30e865" title="Creates a new static LRU hash map with fixed size.">static_lru_create_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00237">237</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00099">static_lru_hash_map_t::table</a>.</p>
</div>
</div>
<a id="a1d284756f5f2f589f20dd0be5a793390" name="a1d284756f5f2f589f20dd0be5a793390"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a1d284756f5f2f589f20dd0be5a793390">&#9670;&#160;</a></span>static_lru_free_slots()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">size_t static_lru_free_slots </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the number of free slots available. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Number of empty slots (size - count). </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00339">339</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00101">static_lru_hash_map_t::count</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>.</p>
</div>
</div>
<a id="aa96225bd1e66d8afd7541bc4587bb88f" name="aa96225bd1e66d8afd7541bc4587bb88f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa96225bd1e66d8afd7541bc4587bb88f">&#9670;&#160;</a></span>static_lru_insert_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool static_lru_insert_map </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>key</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>value</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Inserts a key-value pair into the static LRU hash map. </p>
<p>Adds a new key-value pair to the hash map. If the map is approaching capacity (exceeds STATIC_LRU_EVICTION_LOAD_FACTOR), the least-frequently-used entries are automatically evicted before insertion.</p>
<p>If the key already exists, the value is updated and the access count is incremented.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL. </td></tr>
<tr><td class="paramname">key</td><td>The key to insert. Must not be 0 (reserved for empty slots). </td></tr>
<tr><td class="paramname">value</td><td>The value to associate with the key.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns the result of the insertion operation. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">true</td><td>Successfully inserted a NEW key-value pair. </td></tr>
<tr><td class="paramname">false</td><td>Key already existed; value was updated instead.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>New entries start with access_count = 1. </dd>
<dd>
Updating an existing entry increments its access_count (up to 255). </dd>
<dd>
Time complexity: O(1) average, O(n) when eviction is triggered.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>Using 0 as a key value will result in undefined behavior.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#a450c1d834b74de014c5e943e662b39c0" title="Looks up a value by key in the static LRU hash map.">static_lru_lookup_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00245">245</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00075">lru_kv_pair_t::access_count</a>, <a class="el" href="static__lru__hash__map_8c_source.html#l00064">age_access_counts()</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00104">static_lru_hash_map_t::age_counter</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00101">static_lru_hash_map_t::count</a>, <a class="el" href="static__lru__hash__map_8c_source.html#l00139">evict_lru_entries()</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00073">lru_kv_pair_t::key</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00102">static_lru_hash_map_t::max_count</a>, <a class="el" href="static__lru__hash__map_8c_source.html#l00049">MIN_ACCESS_COUNT</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00055">STATIC_LRU_AGING_INTERVAL</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00099">static_lru_hash_map_t::table</a>, <a class="el" href="static__lru__hash__map_8c_source.html#l00050">TOMBSTONE_KEY</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00074">lru_kv_pair_t::value</a>.</p>
</div>
</div>
<a id="a5deee3df8ccae2c0c34bec4c4a28dfa2" name="a5deee3df8ccae2c0c34bec4c4a28dfa2"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a5deee3df8ccae2c0c34bec4c4a28dfa2">&#9670;&#160;</a></span>static_lru_load_factor()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">double static_lru_load_factor </td>
<td>(</td>
<td class="paramtype">const <a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span></td><td>)</td>
<td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Returns the current load factor of the map. </p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map. Must not be NULL.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Current load factor as a value between 0.0 and 1.0. </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00337">337</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00101">static_lru_hash_map_t::count</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>.</p>
</div>
</div>
<a id="a450c1d834b74de014c5e943e662b39c0" name="a450c1d834b74de014c5e943e662b39c0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a450c1d834b74de014c5e943e662b39c0">&#9670;&#160;</a></span>static_lru_lookup_map()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">bool static_lru_lookup_map </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structstatic__lru__hash__map__t.html">static_lru_hash_map_t</a> *</td> <td class="paramname"><span class="paramname"><em>map</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t</td> <td class="paramname"><span class="paramname"><em>key</em></span>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint64_t *</td> <td class="paramname"><span class="paramname"><em>out_value</em></span>&#160;)</td>
</tr>
</table>
</div><div class="memdoc">
<p>Looks up a value by key in the static LRU hash map. </p>
<p>Searches for the specified key and retrieves its associated value. Unlike the regular hash_map, this function DOES modify the map by incrementing the access_count of the found entry (to track usage frequency).</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">map</td><td>Pointer to the hash map to search. Must not be NULL. </td></tr>
<tr><td class="paramname">key</td><td>The key to search for. Must not be 0. </td></tr>
<tr><td class="paramname">out_value</td><td>Pointer to store the found value. Must not be NULL. Only modified if the key is found.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>Returns whether the key was found in the map. </dd></dl>
<dl class="retval"><dt>Return values</dt><dd>
<table class="retval">
<tr><td class="paramname">true</td><td>Key found. The associated value is written to *out_value. </td></tr>
<tr><td class="paramname">false</td><td>Key not found. *out_value is not modified.</td></tr>
</table>
</dd>
</dl>
<dl class="section note"><dt>Note</dt><dd>This function increments access_count on successful lookups. </dd>
<dd>
Time complexity: O(1) average case.</dd></dl>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="#aa96225bd1e66d8afd7541bc4587bb88f" title="Inserts a key-value pair into the static LRU hash map.">static_lru_insert_map()</a> </dd></dl>
<p class="definition">Definition at line <a class="el" href="static__lru__hash__map_8c_source.html#l00284">284</a> of file <a class="el" href="static__lru__hash__map_8c_source.html">static_lru_hash_map.c</a>.</p>
<p class="reference">References <a class="el" href="static__lru__hash__map_8h_source.html#l00075">lru_kv_pair_t::access_count</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00073">lru_kv_pair_t::key</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00100">static_lru_hash_map_t::size</a>, <a class="el" href="static__lru__hash__map_8h_source.html#l00099">static_lru_hash_map_t::table</a>, <a class="el" href="static__lru__hash__map_8c_source.html#l00050">TOMBSTONE_KEY</a>, and <a class="el" href="static__lru__hash__map_8h_source.html#l00074">lru_kv_pair_t::value</a>.</p>
</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<div id="page-nav" class="page-nav-panel">
<div id="page-nav-resize-handle"></div>
<div id="page-nav-tree">
<div id="page-nav-contents">
</div><!-- page-nav-contents -->
</div><!-- page-nav-tree -->
</div><!-- page-nav -->
</div><!-- container -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="navelem"><a href="dir_d44c64559bbebec7f509842c48db8b23.html">include</a></li><li class="navelem"><a href="dir_aeff2545c9dfcfc842fe9d84b123cb31.html">aaruformat</a></li><li class="navelem"><a href="static__lru__hash__map_8h.html">static_lru_hash_map.h</a></li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.15.0 </li>
</ul>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink