| --- |
| layout: docs |
| title: Get Started |
| permalink: /docs/getstarted.html |
| --- |
| |
| <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;"> <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">"pmalloc"</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">"./pobj_hashmaps.dat"</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<String,</span> <span style="color: #ffffff">Integer></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">"hello"</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">"hello"</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">"world"</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">"world"</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<String,</span> <span style="color: #ffffff">Integer></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">"hello"</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">"world"</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">"test"</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;"> <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">"sort"</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<</span><span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[][]></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<</span><span style="color: #cdcaa9; font-weight: bold">long</span><span style="color: #ffffff">[][]>();</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'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">"1dlong_bubble"</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> |
