Permalink
Browse files

Enhance javadoc comments

  • Loading branch information...
xerial committed Dec 11, 2013
1 parent a5d3eb4 commit 403ef92f0124ecbdb1ab0f0f79bdf332792784df
Showing with 345 additions and 168 deletions.
  1. +0 −9 larray-buffer/src/main/java/xerial/larray/buffer/BufferConfig.java
  2. +3 −97 ...er/src/main/java/xerial/larray/buffer/{OffHeapMemoryAllocator.java → DefaultMemoryCollector.java}
  3. +1 −1 larray-buffer/src/main/java/xerial/larray/buffer/LBuffer.java
  4. +101 −2 larray-buffer/src/main/java/xerial/larray/buffer/LBufferAPI.java
  5. +10 −0 larray-buffer/src/main/java/xerial/larray/buffer/LBufferConfig.java
  6. +0 −29 larray-buffer/src/main/java/xerial/larray/buffer/MemoryAllocator.java
  7. +25 −0 larray-buffer/src/main/java/xerial/larray/buffer/MemoryCollector.java
  8. +84 −0 larray-buffer/src/main/java/xerial/larray/buffer/OffHeapMemory.java
  9. +28 −0 larray-buffer/src/main/java/xerial/larray/buffer/OffHeapMemoryReference.java
  10. +28 −0 larray-buffer/src/main/java/xerial/larray/buffer/WrappedLBuffer.java
  11. +2 −2 ...uffer/src/test/scala/xerial/larray/buffer/{MemoryAllocatorTest.scala → MemoryCollectorTest.scala}
  12. +34 −0 larray-buffer/src/test/scala/xerial/larray/buffer/WrappedLBufferTest.scala
  13. +2 −2 larray-mmap/src/main/java/xerial/larray/mmap/MMapBuffer.java
  14. +3 −2 larray/src/main/java/xerial/larray/japi/LArrayJ.java
  15. +16 −16 larray/src/main/scala/xerial/larray/LArray.scala
  16. +2 −2 larray/src/main/scala/xerial/larray/MappedLByteArray.scala
  17. +3 −3 larray/src/main/scala/xerial/larray/UInt32Array.scala
  18. +2 −2 larray/src/main/scala/xerial/larray/package.scala
  19. +1 −1 larray/src/test/scala/xerial/larray/LArrayTest.scala
@@ -1,9 +0,0 @@
-package xerial.larray.buffer;
-
-/**
- * @author Taro L. Saito
- */
-public class BufferConfig {
-
- public static MemoryAllocator allocator = new OffHeapMemoryAllocator();
-}
@@ -8,99 +8,18 @@
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.atomic.AtomicLong;
-import static xerial.larray.buffer.UnsafeUtil.unsafe;
-/**
- * Stores |(memory size:long)| data ... |
- */
-class OffHeapMemory implements Memory {
-
- private final long _data;
-
- public static long HEADER_SIZE = 8L;
-
- /**
- * Create an empty memory
- */
- public OffHeapMemory() {
- this._data = 0L;
- }
-
- public OffHeapMemory(long address) {
- if(address != 0L)
- this._data = address + HEADER_SIZE;
- else
- this._data = 0L;
- }
-
- public OffHeapMemory(long address, long size) {
- if(address != 0L) {
- this._data = address + HEADER_SIZE;
- unsafe.putLong(address, size);
- }
- else {
- this._data = 0L;
- }
- }
-
- public long headerAddress() {
- return _data - HEADER_SIZE;
- }
- public long size() {
- return (_data == 0) ? 0L : unsafe.getLong(headerAddress()) + HEADER_SIZE;
- }
-
- public long address() {
- return _data;
- }
-
- public long dataSize() {
- return (_data == 0) ? 0L : unsafe.getLong(headerAddress());
- }
-
- public MemoryReference toRef(ReferenceQueue<Memory> queue) {
- return new OffHeapMemoryReference(this, queue);
- }
-
- public void release() {
- if(_data != 0)
- UnsafeUtil.unsafe.freeMemory(headerAddress());
- }
-}
-
-class OffHeapMemoryReference extends MemoryReference {
-
- /**
- * Create a phantom reference
- * @param m the allocated memory
- * @param queue the reference queue to which GCed reference of the Memory will be inserted
- */
- public OffHeapMemoryReference(Memory m, ReferenceQueue<Memory> queue) {
- super(m, queue);
- }
-
- public Memory toMemory() {
- if(address != 0)
- return new OffHeapMemory(address);
- else
- return new OffHeapMemory();
- }
-
- public String name() { return "off-heap"; }
-
-}
-
/**
- * Allocating off-heap memory
+ * A default implementation of MemoryCollector that releases allocated memories in a background thread.
*
* @author Taro L. Saito
*/
-public class OffHeapMemoryAllocator implements MemoryAllocator {
+public class DefaultMemoryCollector implements MemoryCollector {
- private Logger logger = Logger.getLogger(OffHeapMemoryAllocator.class);
+ private Logger logger = Logger.getLogger(DefaultMemoryCollector.class);
// Table from address -> MemoryReference
@@ -140,19 +59,6 @@ public void run() {
*/
public long allocatedSize() { return totalAllocatedSize.get(); }
- public Memory allocate(long size) {
- if(size == 0L)
- return new OffHeapMemory();
-
- // Allocate memory of the given size + HEADER space
- long memorySize = size + OffHeapMemory.HEADER_SIZE;
- long address = unsafe.allocateMemory(memorySize);
- if(logger.isTraceEnabled())
- logger.trace(String.format("Allocated memory address:%x, size:%,d", address, size));
- Memory m = new OffHeapMemory(address, size);
- register(m);
- return m;
- }
public void register(Memory m) {
// Register a memory reference that will be collected upon GC
@@ -14,7 +14,7 @@
* @param size byte size of the array
*/
public LBuffer(long size) {
- super(BufferConfig.allocator.allocate(size));
+ super(OffHeapMemory.allocate(size));
}
@@ -21,6 +21,7 @@
public LBufferAPI() {
}
+
public LBufferAPI(Memory m) {
this.m = m;
}
@@ -71,7 +72,7 @@ public void update(long offset, byte value) {
* getXXX and putXXX methods becomes undefined.
*/
public void release() {
- BufferConfig.allocator.release(m);
+ LBufferConfig.allocator.release(m);
m = null;
}
@@ -85,14 +86,27 @@ public long address() {
return m.address();
}
+ /**
+ * Size of this buffer
+ * @return
+ */
public long size() {
return m.dataSize();
}
+ /**
+ * Clear the buffer by filling with zeros
+ */
public void clear() {
fill(0, size(), (byte) 0);
}
+ /**
+ * Fill the buffer of the specified range with a given value
+ * @param offset
+ * @param length
+ * @param value
+ */
public void fill(long offset, long length, byte value) {
unsafe.setMemory(address() + offset, length, value);
}
@@ -210,6 +224,13 @@ public void putDouble(long offset, double value) {
}
+ /**
+ * Copy the contents of this buffer begginning from the srcOffset to a destination byte array
+ * @param srcOffset
+ * @param destArray
+ * @param destOffset
+ * @param size
+ */
public void copyTo(int srcOffset, byte[] destArray, int destOffset, int size) {
int cursor = destOffset;
for (ByteBuffer bb : toDirectByteBuffers(srcOffset, size)) {
@@ -221,10 +242,23 @@ public void copyTo(int srcOffset, byte[] destArray, int destOffset, int size) {
}
}
- public void copyTo(long srcOffset, LBuffer dest, long destOffset, long size) {
+ /**
+ * Copy the contents of this buffer to the destination LBuffer
+ * @param srcOffset
+ * @param dest
+ * @param destOffset
+ * @param size
+ */
+ public void copyTo(long srcOffset, LBufferAPI dest, long destOffset, long size) {
unsafe.copyMemory(address() + srcOffset, dest.address() + destOffset, size);
}
+ /**
+ * Extract a slice [from, to) of this buffer. This methods creates a copy of the specified region.
+ * @param from
+ * @param to
+ * @return
+ */
public LBuffer slice(long from, long to) {
if(from > to)
throw new IllegalArgumentException(String.format("invalid range %,d to %,d", from, to));
@@ -235,6 +269,24 @@ public LBuffer slice(long from, long to) {
return b;
}
+ /**
+ * Create a view of the range [from, to) of this buffer. Unlike slice(from, to), the generated view
+ * is a reference to this buffer.
+ * @param from
+ * @param to
+ * @return
+ */
+ public WrappedLBuffer view(long from, long to) {
+ if(from > to)
+ throw new IllegalArgumentException(String.format("invalid range %,d to %,d", from, to));
+
+ return new WrappedLBuffer(m, from, to - from);
+ }
+
+ /**
+ * Convert this buffer to a java array.
+ * @return
+ */
public byte[] toArray() {
if (size() > Integer.MAX_VALUE)
throw new IllegalStateException("Cannot create byte array of more than 2GB");
@@ -247,10 +299,21 @@ public LBuffer slice(long from, long to) {
return b;
}
+ /**
+ * Write the buffer contents to the given file channel. This method just
+ * calls channel.write(this.toDirectByteBuffers());
+ * @param channel
+ * @throws IOException
+ */
public void writeTo(FileChannel channel) throws IOException {
channel.write(toDirectByteBuffers());
}
+ /**
+ * Dump the buffer contents to a file
+ * @param file
+ * @throws IOException
+ */
public void writeTo(File file) throws IOException {
FileChannel channel = new FileOutputStream(file).getChannel();
try {
@@ -260,10 +323,24 @@ public void writeTo(File file) throws IOException {
}
}
+ /**
+ * Read the given source byte array, then overwrite the buffer contents
+ * @param src
+ * @param destOffset
+ * @return
+ */
public int readFrom(byte[] src, long destOffset) {
return readFrom(src, 0, destOffset, src.length);
}
+ /**
+ * Read the given source byte arrey, then overwrite the buffer contents
+ * @param src
+ * @param srcOffset
+ * @param destOffset
+ * @param length
+ * @return
+ */
public int readFrom(byte[] src, int srcOffset, long destOffset, int length) {
int readLen = (int) Math.min(src.length - srcOffset, Math.min(size() - destOffset, length));
ByteBuffer b = toDirectByteBuffer(destOffset, readLen);
@@ -273,6 +350,12 @@ public int readFrom(byte[] src, int srcOffset, long destOffset, int length) {
}
+ /**
+ * Create an LBuffer from a given file.
+ * @param file
+ * @return
+ * @throws IOException
+ */
public static LBuffer loadFrom(File file) throws IOException {
FileChannel fin = new FileInputStream(file).getChannel();
long fileSize = fin.size();
@@ -288,10 +371,20 @@ public static LBuffer loadFrom(File file) throws IOException {
}
+ /**
+ * Gives an sequence of ByteBuffers. Writing to these ByteBuffers modifies the contents of this LBuffer.
+ * @return
+ */
public ByteBuffer[] toDirectByteBuffers() {
return toDirectByteBuffers(0, size());
}
+ /**
+ * Gives an sequence of ByteBuffers of a specified range. Writing to these ByteBuffers modifies the contents of this LBuffer.
+ * @param offset
+ * @param size
+ * @return
+ */
public ByteBuffer[] toDirectByteBuffers(long offset, long size) {
long pos = offset;
long blockSize = Integer.MAX_VALUE;
@@ -308,6 +401,12 @@ public static LBuffer loadFrom(File file) throws IOException {
}
+ /**
+ * Gives a ByteBuffer view of the specified range. Writing to the returned ByteBuffer modifies the contenets of this LByteBuffer
+ * @param offset
+ * @param size
+ * @return
+ */
public ByteBuffer toDirectByteBuffer(long offset, int size) {
return UnsafeUtil.newDirectByteBuffer(address() + offset, size);
}
@@ -0,0 +1,10 @@
+package xerial.larray.buffer;
+
+/**
+ * Holding the default memory allocator
+ * @author Taro L. Saito
+ */
+public class LBufferConfig {
+
+ public static MemoryCollector allocator = new DefaultMemoryCollector();
+}
@@ -1,29 +0,0 @@
-package xerial.larray.buffer;
-
-/**
- * Memory allocator interface
- * @author Taro L. Saito
- */
-public interface MemoryAllocator {
-
- /**
- * Allocate a memory of the specified byte length. The allocated memory must be released via `release`
- * as in malloc() in C/C++.
- * @param size byte length of the memory
- * @return allocated memory information
- */
- Memory allocate(long size);
-
- void register(Memory m);
-
- /**
- * Release the memory allocated by allocate(size).
- */
- void release(Memory m);
-
- /**
- * Release the memory allocated by allocate(size).
- */
- void release(MemoryReference ref);
-
-}
Oops, something went wrong.

0 comments on commit 403ef92

Please sign in to comment.