| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <!-- NewPage --> |
| <html lang="en"> |
| <head> |
| <!-- Generated by javadoc (1.8.0_162) on Tue Dec 04 17:15:14 PST 2018 --> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> |
| <title>com.yahoo.memory (com.yahoo.datasketches:memory 0.12.1 API)</title> |
| <meta name="date" content="2018-12-04"> |
| <link rel="stylesheet" type="text/css" href="../../../stylesheet.css" title="Style"> |
| <script type="text/javascript" src="../../../script.js"></script> |
| </head> |
| <body> |
| <script type="text/javascript"><!-- |
| try { |
| if (location.href.indexOf('is-external=true') == -1) { |
| parent.document.title="com.yahoo.memory (com.yahoo.datasketches:memory 0.12.1 API)"; |
| } |
| } |
| catch(err) { |
| } |
| //--> |
| </script> |
| <noscript> |
| <div>JavaScript is disabled on your browser.</div> |
| </noscript> |
| <!-- ========= START OF TOP NAVBAR ======= --> |
| <div class="topNav"><a name="navbar.top"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.top.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../overview-summary.html">Overview</a></li> |
| <li><a href="../../../com/yahoo/memory/package-summary.html">Package</a></li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../index-all.html">Index</a></li> |
| <li><a href="../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev Package</li> |
| <li>Next Package</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../index.html?com/yahoo/memory/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_top"> |
| <li><a href="../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_top"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.top"> |
| <!-- --> |
| </a></div> |
| <!-- ========= END OF TOP NAVBAR ========= --> |
| <div class="header"> |
| <h1 title="Package" class="title">Package com.yahoo.memory</h1> |
| <div class="docSummary"> |
| <div class="block">This package provides high performance primitive and primitive array access to direct (native), |
| off-heap memory and memory-mapped file resources, and consistent views into |
| <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html?is-external=true" title="class or interface in java.nio"><code>ByteBuffer</code></a>, and on-heap primitive arrays.</div> |
| </div> |
| <p>See: <a href="#package.description">Description</a></p> |
| </div> |
| <div class="contentContainer"> |
| <ul class="blockList"> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Interface Summary table, listing interfaces, and an explanation"> |
| <caption><span>Interface Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Interface</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Handle.html" title="interface in com.yahoo.memory">Handle</a></td> |
| <td class="colLast"> |
| <div class="block">A handle for Memory.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/MemoryRequestServer.html" title="interface in com.yahoo.memory">MemoryRequestServer</a></td> |
| <td class="colLast"> |
| <div class="block">The MemoryRequestServer is a callback interface to provide a means for a direct (off-heap), |
| dynamic WritableMemory object to request more memory from the owner of the |
| <a href="../../../com/yahoo/memory/WritableDirectHandle.html" title="class in com.yahoo.memory"><code>WritableDirectHandle</code></a>.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/WritableHandle.html" title="interface in com.yahoo.memory">WritableHandle</a></td> |
| <td class="colLast"> |
| <div class="block">A handle for WritableMemory</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Class Summary table, listing classes, and an explanation"> |
| <caption><span>Class Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Class</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/BaseBuffer.html" title="class in com.yahoo.memory">BaseBuffer</a></td> |
| <td class="colLast"> |
| <div class="block">A new positional API.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Buffer.html" title="class in com.yahoo.memory">Buffer</a></td> |
| <td class="colLast"> |
| <div class="block">Provides read-only, positional primitive and primitive array methods to any of the four resources |
| mentioned in the package level documentation.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/DefaultMemoryRequestServer.html" title="class in com.yahoo.memory">DefaultMemoryRequestServer</a></td> |
| <td class="colLast"> |
| <div class="block">This is a simple implementation of the MemoryRequestServer that creates space on the Java heap |
| for the requesting application.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/MapHandle.html" title="class in com.yahoo.memory">MapHandle</a></td> |
| <td class="colLast"> |
| <div class="block">Gets a Memory for a memory-mapped, read-only file resource, It is highly recommended that this |
| be created inside a <i>try-with-resources</i> statement.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Memory.html" title="class in com.yahoo.memory">Memory</a></td> |
| <td class="colLast"> |
| <div class="block">Provides read-only primitive and primitive array methods to any of the four resources |
| mentioned in the package level documentation.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/UnsafeUtil.html" title="class in com.yahoo.memory">UnsafeUtil</a></td> |
| <td class="colLast"> |
| <div class="block">Provides access to the sun.misc.Unsafe class and its key static fields.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Util.html" title="class in com.yahoo.memory">Util</a></td> |
| <td class="colLast"> </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Util.RandomCodePoints.html" title="class in com.yahoo.memory">Util.RandomCodePoints</a></td> |
| <td class="colLast"> |
| <div class="block">Creates random valid Character Code Points (as integers).</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/WritableBuffer.html" title="class in com.yahoo.memory">WritableBuffer</a></td> |
| <td class="colLast"> |
| <div class="block">Provides read and write, positional primitive and primitive array access to any of the four |
| resources mentioned at the package level.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/WritableDirectHandle.html" title="class in com.yahoo.memory">WritableDirectHandle</a></td> |
| <td class="colLast"> |
| <div class="block">References a WritableMemory for a writable direct memory resource.</div> |
| </td> |
| </tr> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/WritableMapHandle.html" title="class in com.yahoo.memory">WritableMapHandle</a></td> |
| <td class="colLast"> |
| <div class="block">Gets a WritableMemory for a writable memory-mapped file resource.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/WritableMemory.html" title="class in com.yahoo.memory">WritableMemory</a></td> |
| <td class="colLast"> |
| <div class="block">Provides read and write primitive and primitive array access to any of the four resources |
| mentioned at the package level.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| <li class="blockList"> |
| <table class="typeSummary" border="0" cellpadding="3" cellspacing="0" summary="Exception Summary table, listing exceptions, and an explanation"> |
| <caption><span>Exception Summary</span><span class="tabEnd"> </span></caption> |
| <tr> |
| <th class="colFirst" scope="col">Exception</th> |
| <th class="colLast" scope="col">Description</th> |
| </tr> |
| <tbody> |
| <tr class="altColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/ReadOnlyException.html" title="class in com.yahoo.memory">ReadOnlyException</a></td> |
| <td class="colLast"> |
| <div class="block">The exception thrown when attempting to write into a read-only Resource.</div> |
| </td> |
| </tr> |
| <tr class="rowColor"> |
| <td class="colFirst"><a href="../../../com/yahoo/memory/Utf8CodingException.html" title="class in com.yahoo.memory">Utf8CodingException</a></td> |
| <td class="colLast"> |
| <div class="block">This exception will be thrown for errors encountered during either the encoding of characters |
| to Utf8 bytes, or the decoding of Utf8 bytes to characters.</div> |
| </td> |
| </tr> |
| </tbody> |
| </table> |
| </li> |
| </ul> |
| <a name="package.description"> |
| <!-- --> |
| </a> |
| <h2 title="Package com.yahoo.memory Description">Package com.yahoo.memory Description</h2> |
| <div class="block"><p>This package provides high performance primitive and primitive array access to direct (native), |
| off-heap memory and memory-mapped file resources, and consistent views into |
| <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html?is-external=true" title="class or interface in java.nio"><code>ByteBuffer</code></a>, and on-heap primitive arrays. It can be used as a more |
| comprehensive and flexible replacement for <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/ByteBuffer.html?is-external=true" title="class or interface in java.nio"><code>ByteBuffer</code></a>. |
| </p> |
| |
| <p>In addition, this package provides:</p> |
| |
| <ul><li>Two different access APIs: read-only <a href="../../../com/yahoo/memory/Memory.html" title="class in com.yahoo.memory"><code>Memory</code></a> and |
| <a href="../../../com/yahoo/memory/WritableMemory.html" title="class in com.yahoo.memory"><code>WritableMemory</code></a> for absolute offset access, |
| and read-only <a href="../../../com/yahoo/memory/Buffer.html" title="class in com.yahoo.memory"><code>Buffer</code></a> and <a href="../../../com/yahoo/memory/WritableBuffer.html" title="class in com.yahoo.memory"><code>WritableBuffer</code></a> |
| for relative positional access (similar to ByteBuffer).</li> |
| |
| <li>Clean separation of Read-only API from Writable API, which makes writable versus read-only |
| resources detectable at compile time.</li> |
| |
| <li>The conversion from Writable to read-only is just a cast, so no unnecessary objects are |
| created. For example: |
| <blockquote><pre> |
| WritableMemory wMem = ... |
| Memory mem = wMem; |
| </pre></blockquote> |
| </li> |
| |
| <li> <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html?is-external=true" title="class or interface in java.lang"><code>AutoCloseable</code></a> for the external resources that require it, |
| which enables compile-time checks for non-closed resources.</li> |
| |
| <li>Immediate invalidation of all downstream references of an AutoCloseable |
| resource when that resource is closed, either manually or by the JVM. |
| This virtually eliminates the possibility of accidentally writing into the memory space |
| previously owned by a closed resource.</li> |
| |
| <li>Improved performance over the prior Memory implementation.</li> |
| |
| <li>Cleaner internal architecture, which will make it easier to extend in the future.</li> |
| |
| <li>No external dependencies, which makes it simple to install in virtually any Java environment. |
| </li> |
| </ul> |
| |
| <p>More specifically, this package provides access to four different types of resources using |
| two different access APIs. These resources are contiguous blobs of bytes that provide at least |
| byte-level read and write access. The four resources are: |
| |
| <ul><li>Direct (a.k.a. Native) off-heap memory allocated by the user.</li> |
| <li>Memory-mapped files, both writable and read-only.</li> |
| <li><code>ByteBuffers</code>, both heap-based and direct, writable and read-only.</li> |
| <li>Heap-based primitive arrays, which can be accessed as writable or read-only.</li> |
| </ul> |
| |
| <p>The two different access APIs are: |
| <ul><li><i>Memory, WritableMemory</i>: Absolute offset addressing into a resource.</li> |
| <li><i>Buffer, WritableBuffer</i>: Position relative addressing into a resource.</li> |
| </ul> |
| |
| <p>In addition, all combinations of access APIs and backing resources can be accessed via |
| multibyte primitive methods (e.g. |
| <i>getLong(...), getLongArray(...), putLong(...), putLongArray(...)</i>) as either |
| <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/ByteOrder.html?is-external=true#BIG_ENDIAN" title="class or interface in java.nio"><code>ByteOrder.BIG_ENDIAN</code></a> or <a href="https://docs.oracle.com/javase/8/docs/api/java/nio/ByteOrder.html?is-external=true#LITTLE_ENDIAN" title="class or interface in java.nio"><code>ByteOrder.LITTLE_ENDIAN</code></a>. |
| |
| <p>The resources don't know or care about the access APIs, and the access |
| APIs don't really know or care what resource they are accessing. |
| |
| An access API is joined with |
| a resource either with a static factory method or in combination with a |
| <a href="../../../com/yahoo/memory/Handle.html" title="interface in com.yahoo.memory"><code>Handle</code></a>, which is used exclusively for resources that are external to |
| the JVM, such as allocation of direct memory and memory-mapped files. |
| |
| <p>The role of a Handle is to hold onto the reference of a resource that is outside the control |
| of the JVM. The resource is obtained from the handle with <code>get()</code>. |
| |
| <p>When a handle is extended for an AutoCloseable resource and then joined with an access API |
| it becomes an <i>implementation handle</i>. There are 3 implementation handles: |
| |
| <ul><li><a href="../../../com/yahoo/memory/MapHandle.html" title="class in com.yahoo.memory"><code>MapHandle</code></a> for read-only access to a memory-mapped file</li> |
| <li><a href="../../../com/yahoo/memory/WritableMapHandle.html" title="class in com.yahoo.memory"><code>WritableMapHandle</code></a> for writable access to a memory-mapped file</li> |
| <li><a href="../../../com/yahoo/memory/WritableDirectHandle.html" title="class in com.yahoo.memory"><code>WritableDirectHandle</code></a> for writable access to off-heap memory.</li> |
| </ul> |
| |
| <p>As long as the implementation handle is valid the JVM will not attempt to close the resource. |
| |
| <p>An implementation handle implements <a href="https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html?is-external=true" title="class or interface in java.lang"><code>AutoCloseable</code></a>, |
| which also enables compile-time checks for non-closed resources. If a Handle is acquired |
| in a try-with-resources (TWR) block, it's associated resource will be automatically closed by |
| the JVM at the end of the block. |
| The resource can also be explicitly closed by the user by calling <code>Handle.close()</code>. |
| <blockquote><pre> |
| //Using try-with-resources block: |
| try (WritableyMapHandle handle = WritableMemory.map(File file)) { |
| WritableMemory wMem = handle.get(); |
| doWork(wMem) // read and write to memory mapped file. |
| } |
| |
| //Using explicit close(): |
| WritableMapHandle handle = WritableMemory.map(File file); |
| WritableMemory wMem = handle.get(); |
| doWork(wMem) // read and write to memory mapped file. |
| handle.close(); |
| </pre></blockquote> |
| |
| <p>Where it is desirable to pass ownership of the resource (and the <code>close()</code> |
| responsibility) one can not use the TWR block. Instead: |
| <blockquote><pre> |
| WritableMapHandle handler = WritableMemory.map(File file); |
| doWorkAndClose(handle); //passes the handle to object that closes the resource. |
| </pre></blockquote> |
| |
| Whatever part of your process is responsible for allocating a resource external |
| to the JVM must be responsible for closing it or making sure it gets closed. |
| Since only the implementation Handles implement AutoCloseable, you must not let go of the |
| handle reference until you are done with its associated resource. |
| |
| As mentioned above, there are two ways to do this: |
| <ul><li>Use a try-with-resources block. At the end of the block, the JVM will automatically |
| close the resource.</li> |
| |
| <li>If you need to pass an external resource, pass the implementation resource handle, not the |
| access API. This means you are also passing the responsibility to close the resource. |
| If you have different parts of your code holding references to the same handle, |
| whichever one closes it first will make all the other resources invalid, so be careful. |
| As long as there is at least one reference to the handle that is still valid and the resource |
| has not been closed, the resource will remain valid. If you drop all references to all handles, |
| the JVM will eventually close the resource, making it invalid, but it is possible that you might |
| run out of memory first. Depending on this is a bad idea and a could be a serious, |
| hard-to-find bug.</li> |
| </ul> |
| |
| <p>Moving back and forth between <i>Memory</i> and <i>Buffer</i>: |
| <blockquote><pre> |
| Memory mem = ... |
| Buffer buf = mem.asBuffer(); |
| ... |
| Memory mem2 = buf.asMemory(); |
| ... |
| </pre></blockquote> |
| |
| <p>Hierarchical memory regions can be easily created: |
| <blockquote><pre> |
| WritableMemory wMem = ... |
| WritableMemory wReg = wMem.writableRegion(offset, length); //OR |
| Memory reg = wMem.region(offset, length); |
| </pre></blockquote> |
| |
| With asserts enabled in the JVM, all methods are checked for bounds and |
| use-after-close violations.</div> |
| <dl> |
| <dt><span class="simpleTagLabel">Author:</span></dt> |
| <dd>Lee Rhodes</dd> |
| </dl> |
| </div> |
| <!-- ======= START OF BOTTOM NAVBAR ====== --> |
| <div class="bottomNav"><a name="navbar.bottom"> |
| <!-- --> |
| </a> |
| <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div> |
| <a name="navbar.bottom.firstrow"> |
| <!-- --> |
| </a> |
| <ul class="navList" title="Navigation"> |
| <li><a href="../../../overview-summary.html">Overview</a></li> |
| <li><a href="../../../com/yahoo/memory/package-summary.html">Package</a></li> |
| <li>Class</li> |
| <li><a href="package-use.html">Use</a></li> |
| <li><a href="package-tree.html">Tree</a></li> |
| <li><a href="../../../deprecated-list.html">Deprecated</a></li> |
| <li><a href="../../../index-all.html">Index</a></li> |
| <li><a href="../../../help-doc.html">Help</a></li> |
| </ul> |
| </div> |
| <div class="subNav"> |
| <ul class="navList"> |
| <li>Prev Package</li> |
| <li>Next Package</li> |
| </ul> |
| <ul class="navList"> |
| <li><a href="../../../index.html?com/yahoo/memory/package-summary.html" target="_top">Frames</a></li> |
| <li><a href="package-summary.html" target="_top">No Frames</a></li> |
| </ul> |
| <ul class="navList" id="allclasses_navbar_bottom"> |
| <li><a href="../../../allclasses-noframe.html">All Classes</a></li> |
| </ul> |
| <div> |
| <script type="text/javascript"><!-- |
| allClassesLink = document.getElementById("allclasses_navbar_bottom"); |
| if(window==top) { |
| allClassesLink.style.display = "block"; |
| } |
| else { |
| allClassesLink.style.display = "none"; |
| } |
| //--> |
| </script> |
| </div> |
| <a name="skip.navbar.bottom"> |
| <!-- --> |
| </a></div> |
| <!-- ======== END OF BOTTOM NAVBAR ======= --> |
| <p class="legalCopy"><small>Copyright © 2015–2018 <a href="https://www.yahoo.com">Yahoo! Inc.</a>. All rights reserved.</small></p> |
| </body> |
| </html> |
