blob: 0988b0fd914cd4523e0b7569346849c27f1701bf [file] [log] [blame]
<!DOCTYPE HTML>
<html lang="en-US">
<head>
<meta http-equiv="CACHE-CONTROL" content="NO-CACHE">
<meta charset="UTF-8">
<title>Get Started</title>
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="generator" content="Jekyll v2.4.0">
<link rel="stylesheet" href="/css/font-awesome.min.css">
<link rel="stylesheet" href="/css/screen.css">
<link rel="icon" type="image/x-icon" href="/favicon.ico">
<script src="/js/jquery-3.2.1.min.js"></script>
<!--[if lt IE 9]>
<script src="/js/html5shiv.min.js"></script>
<script src="/js/respond.min.js"></script>
<![endif]-->
<script src="/js/screen.js"></script>
<script type="text/javascript" src="/assets/javascripts/bundle.js" charset="utf-8"></script>
</head>
<body>
<header role="banner">
<nav class="mobile-nav show-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/">Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">umentation</span></a>
</li>
</li>
<li class="">
<a href="/downloads/">Downloads</a>
</li>
<li class="">
<a href="/talks/">Talks</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/develop/">Develop</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
</ul>
</nav>
<div class="grid">
<div class="unit one-third center-on-mobiles">
<h1>
<a href="/">
<span class="sr-only">Apache Mnemonic</span>
<img src="/img/mnemonic_logo_v2.png" width="289" alt="Mnemonic Logo" class="logo">
</a>
<a href="https://www.apache.org/events/current-event.html">
<img src="https://www.apache.org/events/current-event-234x60.png"/>
</a>
</h1>
</div>
<nav class="main-nav unit two-thirds hide-on-mobiles">
<ul>
<li class="">
<a href="/">Home</a>
</li>
<li class="current">
<a href="/docs/">Doc<span class="show-on-mobiles">s</span><span class="hide-on-mobiles">umentation</span></a>
</li>
</li>
<li class="">
<a href="/downloads/">Downloads</a>
</li>
<li class="">
<a href="/talks/">Talks</a>
</li>
<li class="">
<a href="/news/">News</a>
</li>
<li class="">
<a href="/develop/">Develop</a>
</li>
<li class="">
<a href="/help/">Help</a>
</li>
</ul>
</nav>
</div>
<!-- Return to Top -->
<a href="#top" id="return-to-top"><i class="fa fa-chevron-up"></i></a>
</header>
<section class="docs">
<div class="grid">
<div class="docs-nav-mobile unit whole show-on-mobiles">
<select onchange="if (this.value) window.location.href=this.value">
<option value="">Navigate the docs…</option>
<optgroup label="Overview">
<option value="/docs/arch.html">Architecture</option>
<option value="/docs/features.html">Features</option>
<option value="/docs/modes.html">Mnemonic Modes</option>
<option value="/docs/memsrvcmp.html">Durable Memory Service Comparison</option>
<option value="/docs/integration.html">Integration with other projects</option>
<option value="/docs/domusecases.html">DOM Use Cases</option>
<option value="/docs/dcmusecases.html">DCM Use Cases</option>
<option value="/docs/msusecases.html">MS Use Cases</option>
<option value="/docs/sparkusecases.html">Apache Spark Integration Use Cases</option>
<option value="/docs/hadoopusecases.html">Apache Hadoop Integration Use Cases</option>
<option value="/docs/gcdata.html">Java GC data</option>
<option value="/docs/security.html">Security</option>
</optgroup>
<optgroup label="Usage">
<option value="/docs/getstarted.html">Get Started</option>
<option value="/docs/devsetup.html">Development Setup</option>
<option value="/docs/submitchanges.html">Submit Changes</option>
<option value="/docs/build.html">Project Build</option>
<option value="/docs/runtest.html">Run tests</option>
<option value="/docs/docker.html">Docker usage</option>
</optgroup>
</select>
</div>
<div class="unit four-fifths">
<article>
<h1>Get Started</h1>
<section class="example">
<a class="title" href="https://github.com/apache/mnemonic/blob/master/mnemonic-collections/src/test/java/org/apache/mnemonic/collections/DurableHashMapNGTest.java" target="_blank"> Durable Map </a>
<div class="code">
<div style="background: #111111; overflow:auto;width:auto;border:solid gray;border-width:.1em .1em .1em .1em;padding:.2em .6em;">&nbsp<pre style="margin: 0; line-height: 125%"> <span style="color: #008800; font-style: italic; background-color: #0f140f">/* initialize a memory allocator */</span>
<span style="color: #ffffff">m_act</span> <span style="color: #ffffff">=</span> <span style="color: #fb660a; font-weight: bold">new</span> <span style="color: #ffffff">NonVolatileMemAllocator(</span>
<span class="tooltip" data-tooltip="a memory service instance"><span style="color: #ffffff">Utils.</span><span style="color: #ff0086; font-weight: bold">getNonVolatileMemoryAllocatorService</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;pmalloc&quot;</span><span style="color: #ffffff">)</span></span><span style="color: #ffffff">,</span>
<span class="tooltip" data-tooltip="the capacity"><span style="color: #0086f7; font-weight: bold">1024</span> <span style="color: #ffffff">*</span> <span style="color: #0086f7; font-weight: bold">1024</span> <span style="color: #ffffff">*</span> <span style="color: #0086f7; font-weight: bold">1024L</span></span><span style="color: #ffffff">,</span>
<span class="tooltip" data-tooltip="an uri associated with memory service"><span style="color: #0086d2">&quot;./pobj_hashmaps.dat&quot;</span></span><span style="color: #ffffff">,</span>
<span class="tooltip" data-tooltip="open a new memory space"><span style="color: #fb660a; font-weight: bold">true</span></span><span style="color: #ffffff">);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* prepare generic types in order as an array for durable map</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> you can specify any durable type here </span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> e.g. durable object, durable buffer/chunk, durable list/map/set */</span>
<span style="color: #ffffff">DurableType</span> <span style="color: #ffffff">gtypes[]</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">{</span><span class="tooltip" data-tooltip="map key is string type"><span style="color: #ffffff">DurableType.</span><span style="color: #ff0086; font-weight: bold">STRING</span></span><span style="color: #ffffff">,</span> <span class="tooltip" data-tooltip=" map value is integer type"><span style="color: #ffffff">DurableType.</span><span style="color: #ff0086; font-weight: bold">INTEGER</span></span><span style="color: #ffffff">};</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* create a new durable map through durable map factory,</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> the durable map store your objects on external memory-class storage</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> with no need to do serialization at all */</span>
<span style="color: #ffffff">DurableHashMap&lt;String,</span> <span style="color: #ffffff">Integer&gt;</span> <span style="color: #ffffff">map</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">DurableHashMapFactory.</span><span style="color: #ff0086; font-weight: bold">create</span><span style="color: #ffffff">(</span>
<span class="tooltip" data-tooltip="a memory allocator"><span style="color: #ffffff">m_act</span></span><span style="color: #ffffff">,</span> <span class="tooltip" data-tooltip="an array of generic type factory proxy for user durable generic object"><span style="color: #fb660a; font-weight: bold">null</span></span><span style="color: #ffffff">,</span> <span class="tooltip" data-tooltip="an array of generic types"><span style="color: #ffffff">gtypes</span></span><span style="color: #ffffff">,</span> <span class="tooltip" data-tooltip="initial capacity"><span style="color: #ffffff">mInitialCapacity</span></span><span style="color: #ffffff">,</span> <span class="tooltip" data-tooltip="autoclaim is disabled"><span style="color: #fb660a; font-weight: bold">false</span></span><span style="color: #ffffff">);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* fetch the handler of the durable map, </span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> it is just a long type value.</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> it is used for restore this durable map back later,</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> you can put this handler anywhere you like</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> e.g. durable key-value store, durable buffer */</span>
<span style="color: #ffffff">Long</span> <span style="color: #ffffff">handler</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">map.</span><span style="color: #ff0086; font-weight: bold">getHandler</span><span style="color: #ffffff">();</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* use this durable map as usual */</span>
<span style="color: #ffffff">Integer</span> <span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">map.</span><span style="color: #ff0086; font-weight: bold">put</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;hello&quot;</span><span style="color: #ffffff">,</span> <span style="color: #0086f7; font-weight: bold">1</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertNull</span><span style="color: #ffffff">(val);</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">map.</span><span style="color: #ff0086; font-weight: bold">put</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;hello&quot;</span><span style="color: #ffffff">,</span> <span style="color: #0086f7; font-weight: bold">3</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertEquals</span><span style="color: #ffffff">(</span><span style="color: #0086f7; font-weight: bold">1</span><span style="color: #ffffff">,</span> <span style="color: #ffffff">val.</span><span style="color: #ff0086; font-weight: bold">intValue</span><span style="color: #ffffff">());</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">map.</span><span style="color: #ff0086; font-weight: bold">put</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;world&quot;</span><span style="color: #ffffff">,</span> <span style="color: #0086f7; font-weight: bold">2</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertNull</span><span style="color: #ffffff">(val);</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">map.</span><span style="color: #ff0086; font-weight: bold">remove</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;world&quot;</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertEquals</span><span style="color: #ffffff">(</span><span style="color: #0086f7; font-weight: bold">2</span><span style="color: #ffffff">,</span> <span style="color: #ffffff">val.</span><span style="color: #ff0086; font-weight: bold">intValue</span><span style="color: #ffffff">());</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* restore the same durable map from the stored handler </span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> with no need to do de-serializatoin */</span>
<span style="color: #ffffff">DurableHashMap&lt;String,</span> <span style="color: #ffffff">Integer&gt;</span> <span style="color: #ffffff">restoredMap</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">DurableHashMapFactory.</span><span style="color: #ff0086; font-weight: bold">restore</span><span style="color: #ffffff">(</span>
<span style="color: #ffffff">m_act,</span> <span style="color: #fb660a; font-weight: bold">null</span><span style="color: #ffffff">,</span> <span style="color: #ffffff">gtypes,</span> <span class="tooltip" data-tooltip="the handler used to restore durable map"><span style="color: #ffffff">handler</span></span><span style="color: #ffffff">,</span> <span style="color: #fb660a; font-weight: bold">false</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">restoredMap.</span><span style="color: #ff0086; font-weight: bold">get</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;hello&quot;</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertEquals</span><span style="color: #ffffff">(</span><span style="color: #0086f7; font-weight: bold">3</span><span style="color: #ffffff">,</span> <span style="color: #ffffff">val.</span><span style="color: #ff0086; font-weight: bold">intValue</span><span style="color: #ffffff">());</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">restoredMap.</span><span style="color: #ff0086; font-weight: bold">get</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;world&quot;</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertNull</span><span style="color: #ffffff">(val);</span>
<span style="color: #ffffff">val</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">restoredMap.</span><span style="color: #ff0086; font-weight: bold">get</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;test&quot;</span><span style="color: #ffffff">);</span>
<span style="color: #ffffff">AssertJUnit.</span><span style="color: #ff0086; font-weight: bold">assertNull</span><span style="color: #ffffff">(val);</span>
</pre></div>
</div>
</section>
<section class="example">
<a class="title" href="https://github.com/apache/mnemonic/blob/master/mnemonic-benches/mnemonic-sort-bench/src/main/java/org/apache/mnemonic/bench/DNCSTextFileSort.java" target="_blank"> Durable Sorting </a>
<div class="code">
<div style="background: #111111; overflow:auto;width:auto;border:solid gray;border-width:.1em .1em .1em .1em;padding:.2em .6em;">&nbsp<pre style="margin: 0; line-height: 125%"> <span style="color: #008800; font-style: italic; background-color: #0f140f">/* get sort service instance */</span>
<span style="color: #ffffff">GeneralComputingService</span> <span class="tooltip" data-tooltip="a general native computing instance"><span style="color: #ffffff">gcsvr</span></span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">Utils.</span><span style="color: #ff0086; font-weight: bold">getGeneralComputingService</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;sort&quot;</span><span style="color: #ffffff">);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* instantiate a value info object */</span>
<span style="color: #ffffff">ValueInfo</span> <span class="tooltip" data-tooltip="an info object describes a single value or a set of values "><span style="color: #ffffff">vinfo</span></span> <span style="color: #ffffff">=</span> <span style="color: #fb660a; font-weight: bold">new</span> <span style="color: #ffffff">ValueInfo();</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* instantiate an object stack list */</span>
<span style="color: #ffffff">List&lt;</span><span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[][]&gt;</span> <span class="tooltip" data-tooltip="a stack of object info that could be retrieved from durable objects"><span style="color: #ffffff">objstack</span></span> <span style="color: #ffffff">=</span> <span style="color: #fb660a; font-weight: bold">new</span> <span style="color: #ffffff">ArrayList&lt;</span><span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[][]&gt;();</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* fill it up with durable object info in order */</span>
<span style="color: #ffffff">objstack.</span><span style="color: #ff0086; font-weight: bold">add</span><span style="color: #ffffff">(</span><span style="color: #fb660a; font-weight: bold">this</span><span style="color: #ffffff">.</span><span style="color: #ff0086; font-weight: bold">ostack</span><span style="color: #ffffff">);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* configure the field id info stack to specify which field value</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> need to be sorted */</span>
<span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[][]</span> <span class="tooltip" data-tooltip="a stack of field info"><span style="color: #ffffff">fidinfostack</span></span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">{ {</span><span style="color: #0086f7; font-weight: bold">2L</span><span style="color: #ffffff">,</span> <span style="color: #0086f7; font-weight: bold">1L</span><span style="color: #ffffff">} };</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* assign the handler of a durable list to vinfo.handler */</span>
<span style="color: #ffffff">vinfo.</span><span style="color: #ff0086; font-weight: bold">handler</span> <span style="color: #ffffff">=</span> <span style="color: #fb660a; font-weight: bold">this</span><span style="color: #ffffff">.</span><span style="color: #ff0086; font-weight: bold">head</span><span style="color: #ffffff">;</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* set a translate table from handler&#39;s memory allocator */</span>
<span style="color: #ffffff">vinfo.</span><span style="color: #ff0086; font-weight: bold">transtable</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">m_act.</span><span style="color: #ff0086; font-weight: bold">getTranslateTable</span><span style="color: #ffffff">();</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* specify the durable type of value */</span>
<span style="color: #ffffff">vinfo.</span><span style="color: #ff0086; font-weight: bold">dtype</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">DurableType.</span><span style="color: #ff0086; font-weight: bold">LONG</span><span style="color: #ffffff">;</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* generate an array of frame from</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> object info stack and field info stack */</span>
<span style="color: #ffffff">vinfo.</span><span style="color: #ff0086; font-weight: bold">frames</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">Utils.</span><span style="color: #ff0086; font-weight: bold">genNativeParamForm</span><span style="color: #ffffff">(objstack,</span> <span style="color: #ffffff">fidinfostack);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* wrap a set of value info as an array */</span>
<span style="color: #ffffff">ValueInfo[]</span> <span style="color: #ffffff">vinfos</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">{vinfo};</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* perform the sorting operation,</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> the durable list and its value are not marshaled or un-marshaled</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f"> across native boundary */</span>
<span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[]</span> <span style="color: #ffffff">ret</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">gcsvr.</span><span style="color: #ff0086; font-weight: bold">perform</span><span style="color: #ffffff">(</span><span style="color: #0086d2">&quot;1dlong_bubble&quot;</span><span style="color: #ffffff">,</span> <span style="color: #ffffff">vinfos);</span>
<span style="color: #008800; font-style: italic; background-color: #0f140f">/* return the handler of new head of sorted durable list */</span>
<span style="color: #fb660a; font-weight: bold">this</span><span style="color: #ffffff">.</span><span style="color: #ff0086; font-weight: bold">head</span> <span style="color: #ffffff">=</span> <span style="color: #ffffff">ret[</span><span style="color: #0086f7; font-weight: bold">0</span><span style="color: #ffffff">];</span>
</pre></div>
</div>
</section>
<div class="section-nav">
<div class="left align-right">
<a href="/docs/security.html" class="prev">Back</a>
</div>
<div class="right align-left">
<a href="/docs/devsetup.html" class="next">Next</a>
</div>
</div>
<div class="clear"></div>
</article>
</div>
<div class="unit one-fifth hide-on-mobiles">
<aside>
<h4>Overview</h4>
<ul>
<li class=""><a href="/docs/arch.html">Architecture</a></li>
<li class=""><a href="/docs/features.html">Features</a></li>
<li class=""><a href="/docs/modes.html">Mnemonic Modes</a></li>
<li class=""><a href="/docs/memsrvcmp.html">Durable Memory Service Comparison</a></li>
<li class=""><a href="/docs/integration.html">Integration with other projects</a></li>
<li class=""><a href="/docs/domusecases.html">DOM Use Cases</a></li>
<li class=""><a href="/docs/dcmusecases.html">DCM Use Cases</a></li>
<li class=""><a href="/docs/msusecases.html">MS Use Cases</a></li>
<li class=""><a href="/docs/sparkusecases.html">Apache Spark Integration Use Cases</a></li>
<li class=""><a href="/docs/hadoopusecases.html">Apache Hadoop Integration Use Cases</a></li>
<li class=""><a href="/docs/gcdata.html">Java GC data</a></li>
<li class=""><a href="/docs/security.html">Security</a></li>
</ul>
<h4>Usage</h4>
<ul>
<li class="current"><a href="/docs/getstarted.html">Get Started</a></li>
<li class=""><a href="/docs/devsetup.html">Development Setup</a></li>
<li class=""><a href="/docs/submitchanges.html">Submit Changes</a></li>
<li class=""><a href="/docs/build.html">Project Build</a></li>
<li class=""><a href="/docs/runtest.html">Run tests</a></li>
<li class=""><a href="/docs/docker.html">Docker usage</a></li>
</ul>
</aside>
</div>
<div class="clear"></div>
</div>
</section>
<footer role="contentinfo">
<p><div align="center">Apache Mnemonic, Mnemonic, Apache, and the Mnemonic logo are trademarks of The Apache Software Foundation.</div>
<div align="center"> Copyright &copy;&nbsp;2021 <a href="https://www.apache.org/">The Apache Software Foundation</a></div></p>
</footer>
<script>
var anchorForId = function (id) {
var anchor = document.createElement("a");
anchor.className = "header-link";
anchor.href = "#" + id;
anchor.innerHTML = "<span class=\"sr-only\">Permalink</span><i class=\"fa fa-link\"></i>";
anchor.title = "Permalink";
return anchor;
};
var linkifyAnchors = function (level, containingElement) {
var headers = containingElement.getElementsByTagName("h" + level);
for (var h = 0; h < headers.length; h++) {
var header = headers[h];
if (typeof header.id !== "undefined" && header.id !== "") {
header.appendChild(anchorForId(header.id));
}
}
};
document.onreadystatechange = function () {
if (this.readyState === "complete") {
var contentBlock = document.getElementsByClassName("docs")[0] || document.getElementsByClassName("news")[0];
if (!contentBlock) {
return;
}
for (var level = 1; level <= 6; level++) {
linkifyAnchors(level, contentBlock);
}
}
};
</script>
</body>
</html>