Skip to content
Permalink
Browse files
Merge pull request #95 from DataSketches/Resources
Add resourceFence for allocate direct and map doClose().
  • Loading branch information
leerho committed Dec 11, 2018
2 parents ba35175 + 2fcc35f commit 1a753ac08023aa0d41905cbcd51280e047a9fb39
Showing 10 changed files with 89 additions and 38 deletions.
@@ -62,14 +62,18 @@ public void close() {
}

boolean doClose() {
if (deallocator.deallocate(false)) {
// This Cleaner.clean() call effectively just removes the Cleaner from the internal linked
// list of all cleaners. It will delegate to Deallocator.deallocate() which will be a no-op
// because the valid state is already changed.
cleaner.clean();
return true;
} else {
return false;
try {
if (deallocator.deallocate(false)) {
// This Cleaner.clean() call effectively just removes the Cleaner from the internal linked
// list of all cleaners. It will delegate to Deallocator.deallocate() which will be a no-op
// because the valid state is already changed.
cleaner.clean();
return true;
} else {
return false;
}
} finally {
BaseState.reachabilityFence(this);
}
}

@@ -138,14 +138,18 @@ public void close() {
}

boolean doClose() {
if (deallocator.deallocate(false)) {
// This Cleaner.clean() call effectively just removes the Cleaner from the internal linked
// list of all cleaners. It will delegate to Deallocator.deallocate() which will be a no-op
// because the valid state is already changed.
cleaner.clean();
return true;
} else {
return false;
try {
if (deallocator.deallocate(false)) {
// This Cleaner.clean() call effectively just removes the Cleaner from the internal linked
// list of all cleaners. It will delegate to Deallocator.deallocate() which will be a no-op
// because the valid state is already changed.
cleaner.clean();
return true;
} else {
return false;
}
} finally {
BaseState.reachabilityFence(this);
}
}

@@ -426,6 +426,9 @@ public static final long getCurrentDirectMemoryMapAllocated() {
return BaseState.currentDirectMemoryMapAllocated_.get();
}

//REACHABILITY FENCE
static void reachabilityFence(@SuppressWarnings("unused") final Object obj) { }

//TO STRING
/**
* Returns a formatted hex string of a range of this object.
@@ -6,8 +6,33 @@
package com.yahoo.memory;

/**
* A handle for Memory.
* A handle for read-only resource.
*
* <p>The purpose of a Handle is to
* <ul><li>Provide a <i>strong reference</i> to an external <i>resource</i>.</li>
* <li>Extend <i>AutoCloseable</i>, which provides a means to close the resource.</li>
* <li>Provide other capabilites unique to a particular resource.</li>
* </ul>
*
* <p>Maintaining strong references to external resources is critical to avoid accidental
* <i>use-after-free</i> scenarios, where the Garbage Collector will automatically close an external
* resource if there are no remaining strong references to it. One very common mistake, is to allow
* a newly created Handle to fall out-of-scope from the block where it was created, such as from a
* try-with-resources statement. The Garbage Collector will eventually close the Handle referent
* resource.</p>
*
* <p>Another <i>use-after-free</i> scenario is where a thread or agent, with access to the
* Handle, prematurely closes a resource, when another part of the program is still using that
* same resource. Avoiding this scenario requires careful planning and design.</p>
*
* <p>The design philosophy here is that whatever process created the external resource has the
* responsibility to <i>close()</i> that resource when it is no longer needed. This responsibility
* can be delegated, by passing the appropriate Handle to the delegatee. In principle, however, at
* any one time there should be only one agent holding the Handle and responsible for closing the
* resource.</p>
*
* @author Lee Rhodes
* @author Roman Leventov
*/
public interface Handle extends AutoCloseable {

@@ -6,11 +6,11 @@
package com.yahoo.memory;

/**
* 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.
* A Handle for a memory-mapped, read-only file resource.
* Please read Javadocs for {@link Handle}.
*
* @author Roman Leventov
* @author Lee Rhodes
* @author Roman Leventov
*/
//Joins a Read-only Handle with an AutoCloseable Map resource.
public class MapHandle implements Map, Handle {
@@ -76,7 +76,8 @@ public static Memory wrap(final ByteBuffer byteBuf, final ByteOrder byteOrder) {
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.map(...)</i>.
* @param file the given file to map
* @return <i>MapHandle</i> for managing the mapped Memory
* @return <i>MapHandle</i> for managing the mapped Memory.
* Please read Javadocs for {@link Handle}.
* @throws IOException if file not found or a RuntimeException.
*/
public static MapHandle map(final File file) throws IOException {
@@ -93,7 +94,8 @@ public static MapHandle map(final File file) throws IOException {
* @param fileOffsetBytes the position in the given file in bytes. It may not be negative.
* @param capacityBytes the size of the mapped Memory. It may not be negative or zero.
* @param byteOrder the byte order to be used for the mapped Memory. It may not be null.
* @return <i>MapHandle</i> for managing the mapped Memory
* @return <i>MapHandle</i> for managing the mapped Memory.
* Please read Javadocs for {@link Handle}.
* @throws IOException if file not found or a RuntimeException.
*/
public static MapHandle map(final File file, final long fileOffsetBytes, final long capacityBytes,
@@ -201,7 +203,8 @@ public static MapHandle map(final File file, final long fileOffsetBytes, final l
//ACCESS PRIMITIVE HEAP ARRAYS for readOnly
/**
* Wraps the given primitive array for read operations assuming native byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -215,7 +218,8 @@ public static Memory wrap(final boolean[] arr) {

/**
* Wraps the given primitive array for read operations assuming native byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -228,7 +232,8 @@ public static Memory wrap(final byte[] arr) {

/**
* Wraps the given primitive array for read operations with the given byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -303,7 +308,8 @@ public static Memory wrap(final int[] arr) {

/**
* Wraps the given primitive array for read operations assuming native byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -317,7 +323,8 @@ public static Memory wrap(final long[] arr) {

/**
* Wraps the given primitive array for read operations assuming native byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -331,7 +338,8 @@ public static Memory wrap(final float[] arr) {

/**
* Wraps the given primitive array for read operations assuming native byte order. If the array
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are unspecified.
* size is zero, backing storage and byte order of the returned <i>Memory</i> object are
* unspecified.
*
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>Memory.wrap(...)</i>.
@@ -6,11 +6,11 @@
package com.yahoo.memory;

/**
* References a WritableMemory for a writable direct memory resource. It is highly recommended that
* this be created inside a <i>try-with-resources</i> statement.
* A Handle for a writable direct memory resource.
* Please read Javadocs for {@link Handle}.
*
* @author Roman Leventov
* @author Lee Rhodes
* @author Roman Leventov
*/
//Joins a WritableMemory with a writable, AutoCloseable AllocateDirect resource
public final class WritableDirectHandle implements WritableHandle {
@@ -6,8 +6,11 @@
package com.yahoo.memory;

/**
* A handle for WritableMemory
* A Handle for writable direct memory or a memory-mapped, writable file resource.
* Please read Javadocs for {@link Handle}.
*
* @author Lee Rhodes
* @author Roman Leventov
*/
public interface WritableHandle extends Handle {

@@ -6,8 +6,8 @@
package com.yahoo.memory;

/**
* Gets a WritableMemory for a writable memory-mapped file resource. It is highly recommended
* that this be created inside a <i>try-with-resources</i> statement.
* A Handle for a memory-mapped, writable file resource.
* Please read Javadocs for {@link Handle}.
*
* @author Roman Leventov
* @author Lee Rhodes
@@ -72,7 +72,8 @@ public static WritableMemory wrap(final ByteBuffer byteBuf, final ByteOrder byte
* <p><b>Note:</b> Always qualify this method with the class name, e.g.,
* <i>WritableMemory.map(...)</i>.
* @param file the given file to map
* @return WritableMapHandle for managing the mapped Memory
* @return WritableMapHandle for managing the mapped Memory.
* Please read Javadocs for {@link Handle}.
* @throws IOException file not found or a RuntimeException.
*/
public static WritableMapHandle map(final File file) throws IOException {
@@ -89,7 +90,8 @@ public static WritableMapHandle map(final File file) throws IOException {
* @param fileOffsetBytes the position in the given file in bytes. It may not be negative.
* @param capacityBytes the size of the mapped Memory. It may not be negative or zero.
* @param byteOrder the byte order to be used for the given file. It may not be null.
* @return WritableMapHandle for managing the mapped Memory
* @return WritableMapHandle for managing the mapped Memory.
* Please read Javadocs for {@link Handle}.
* @throws IOException file not found or RuntimeException, etc.
*/
public static WritableMapHandle map(final File file, final long fileOffsetBytes,
@@ -117,7 +119,8 @@ public static WritableMapHandle map(final File file, final long fileOffsetBytes,
* and to call <i>close()</i> when done.</p>
*
* @param capacityBytes the size of the desired memory in bytes.
* @return WritableDirectHandle for this off-heap resource
* @return WritableDirectHandle for this off-heap resource.
* Please read Javadocs for {@link Handle}.
*/
public static WritableDirectHandle allocateDirect(final long capacityBytes) {
return allocateDirect(capacityBytes, null);
@@ -136,7 +139,8 @@ public static WritableDirectHandle allocateDirect(final long capacityBytes) {
* @param capacityBytes the size of the desired memory in bytes.
* @param memReqSvr A user-specified MemoryRequestServer.
* This is a callback mechanism for a user client of direct memory to request more memory.
* @return WritableHandle for this off-heap resource
* @return WritableHandle for this off-heap resource.
* Please read Javadocs for {@link Handle}.
*/
public static WritableDirectHandle allocateDirect(final long capacityBytes,
final MemoryRequestServer memReqSvr) {

0 comments on commit 1a753ac

Please sign in to comment.