This is an automated email from the ASF dual-hosted git repository.
ravindra pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow.git
The following commit(s) were added to refs/heads/master by this push:
new d2e1ee9 ARROW-4743: [Java] Add javadoc missing in classes and methods
in java…
d2e1ee9 is described below
commit d2e1ee9edd70c05145adb0f4fc0da38de3be4e6d
Author: Micah Kornfield <emkornfi...@gmail.com>
AuthorDate: Thu Mar 14 11:34:22 2019 +0530
ARROW-4743: [Java] Add javadoc missing in classes and methods in java…
This is the result finding errors after applying the following diff to
suppressions.xml (note for some reason this only seems to highlight method
level documentation issue not class ones, if anyone can point out the right
configuration knob to automatically detect missing class docs as well I would
appreciate it):
--- a/java/dev/checkstyle/suppressions.xml
+++ b/java/dev/checkstyle/suppressions.xml
@@ -24,17 +24,12 @@
<suppress checks="JavadocPackage"
files=".*[\\/]maven-archetypes[\\/].*"/>
<suppress checks="JavadocPackage" files=".*[\\/]examples[\\/].*"/>
- <!-- suppress all checks in the generated directories -->
- <suppress checks=".*" files=".+[\\/]generated[\\/].+\.java" />
- <suppress checks=".*" files=".+[\\/]generated-sources[\\/].+\.java" />
+ <!-- suppress all checks in the generated test directories -->
<suppress checks=".*" files=".+[\\/]generated-test-sources[\\/].+\.java"
/>
<!-- suppress files that include additional lines in license -->
<suppress checks="Header" files="AutoCloseables.java|Collections2.java"
/>
- <!-- TODO: Temporarily suppress missing Javadocs -->
- <suppress checks="JavadocMethod" message="Missing a Javadoc comment."
files=".*" />
Author: Micah Kornfield <emkornfi...@gmail.com>
Closes #3792 from emkornfield/javadoc and squashes the following commits:
d01c123c <Micah Kornfield> Address code review feedback
a64c11ec <Micah Kornfield> ARROW-4743: Add javadoc missing in classes and
methods in java/memory
---
.../src/main/java/io/netty/buffer/ArrowBuf.java | 42 ++++++++++++++++++++++
.../io/netty/buffer/MutableWrappedByteBuf.java | 5 ++-
.../io/netty/buffer/PooledByteBufAllocatorL.java | 3 ++
.../org/apache/arrow/memory/BaseAllocator.java | 16 +++++++++
.../org/apache/arrow/memory/BoundsChecking.java | 7 ++++
.../apache/arrow/memory/OutOfMemoryException.java | 8 ++++-
.../org/apache/arrow/memory/RootAllocator.java | 5 +--
.../test/java/io/netty/buffer/TestArrowBuf.java | 3 +-
8 files changed, 82 insertions(+), 7 deletions(-)
diff --git a/java/memory/src/main/java/io/netty/buffer/ArrowBuf.java
b/java/memory/src/main/java/io/netty/buffer/ArrowBuf.java
index 607f8ca..bb6a940 100644
--- a/java/memory/src/main/java/io/netty/buffer/ArrowBuf.java
+++ b/java/memory/src/main/java/io/netty/buffer/ArrowBuf.java
@@ -41,6 +41,18 @@ import org.apache.arrow.util.Preconditions;
import io.netty.util.internal.PlatformDependent;
+/**
+ * ArrowBuf is the abstraction around raw byte arrays that
+ * comprise arrow data structures.
+ *
+ *
+ * <p>Specifically, it serves as a facade over
+ * {@linkplain UnsafeDirectLittleEndian} memory objects that hides the details
+ * of raw memory addresses.
+ *
+ * <p>ArrowBuf supports reference counting and ledgering to closely track where
+ * memory is being used.
+ */
public final class ArrowBuf extends AbstractByteBuf implements AutoCloseable {
private static final org.slf4j.Logger logger =
org.slf4j.LoggerFactory.getLogger(ArrowBuf.class);
@@ -60,6 +72,17 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
new HistoricalLog(BaseAllocator.DEBUG_LOG_LENGTH, "ArrowBuf[%d]", id) :
null;
private volatile int length;
+ /**
+ * Constructs a new ArrowBuf
+ * @param refCnt The atomic integer to use for reference counting this
buffer.
+ * @param ledger The ledger to use for tracking memory usage of this buffer.
+ * @param byteBuf The underlying storage for this buffer.
+ * @param manager The manager that handles replacing this buffer.
+ * @param alloc The allocator for the buffer (needed for superclass
compatibility)
+ * @param offset The byte offset into <code>byteBuf</code> this buffer
starts at.
+ * @param length The byte length of this buffer
+ * @param isEmpty Indicates if this buffer is empty which enables some
optimizations.
+ */
public ArrowBuf(
final AtomicInteger refCnt,
final BufferLedger ledger,
@@ -69,6 +92,7 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
final int offset,
final int length,
boolean isEmpty) {
+ // TODO(emkornfield): Should this be byteBuf.maxCapacity - offset?
super(byteBuf.maxCapacity());
this.refCnt = refCnt;
this.udle = byteBuf;
@@ -86,6 +110,7 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
}
+ /** Returns a debug friendly string for the given ByteBuf. */
public static String bufferState(final ByteBuf buf) {
final int cap = buf.capacity();
final int mcap = buf.maxCapacity();
@@ -97,6 +122,10 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
cap, mcap, ri, rb, wi, wb);
}
+ /**
+ * Returns <code>this</code> if size is less then {@link #capacity()},
otherwise
+ * delegates to {@link BufferManager#replace(ArrowBuf, int)} to get a new
buffer.
+ */
public ArrowBuf reallocIfNeeded(final int size) {
Preconditions.checkArgument(size >= 0, "reallocation size must be
non-negative");
@@ -928,6 +957,10 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
return this;
}
+ /**
+ * Copies length bytes from src starting at srcIndex
+ * to this buffer starting at index.
+ */
public ArrowBuf setBytes(int index, ByteBuffer src, int srcIndex, int
length) {
if (src.isDirect()) {
checkIndex(index, length);
@@ -1050,6 +1083,7 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
return id;
}
+ /** Returns all ledger information with stack traces as a string. */
public String toVerboseString() {
if (isEmpty) {
return toString();
@@ -1060,6 +1094,14 @@ public final class ArrowBuf extends AbstractByteBuf
implements AutoCloseable {
return sb.toString();
}
+ /**
+ * Prints information of this buffer into <code>sb</code> at the given
+ * indentation and verbosity level.
+ *
+ * <p>It will include history if BaseAllocator.DEBUG is true and
+ * the verbosity.includeHistoricalLog are true.
+ *
+ */
public void print(StringBuilder sb, int indent, Verbosity verbosity) {
BaseAllocator.indent(sb, indent).append(toString());
diff --git
a/java/memory/src/main/java/io/netty/buffer/MutableWrappedByteBuf.java
b/java/memory/src/main/java/io/netty/buffer/MutableWrappedByteBuf.java
index 008cc2b..5221dd3 100644
--- a/java/memory/src/main/java/io/netty/buffer/MutableWrappedByteBuf.java
+++ b/java/memory/src/main/java/io/netty/buffer/MutableWrappedByteBuf.java
@@ -29,9 +29,8 @@ import java.nio.channels.ScatteringByteChannel;
import io.netty.util.ByteProcessor;
/**
- * This is basically a complete copy of DuplicatedByteBuf. We copy because we
want to override
- * some behaviors and make
- * buffer mutable.
+ * This is basically a complete copy of netty's DuplicatedByteBuf. We copy
because we want to override
+ * some behaviors and make buffer mutable.
*/
abstract class MutableWrappedByteBuf extends AbstractByteBuf {
diff --git
a/java/memory/src/main/java/io/netty/buffer/PooledByteBufAllocatorL.java
b/java/memory/src/main/java/io/netty/buffer/PooledByteBufAllocatorL.java
index 1f50ad3..a677f03 100644
--- a/java/memory/src/main/java/io/netty/buffer/PooledByteBufAllocatorL.java
+++ b/java/memory/src/main/java/io/netty/buffer/PooledByteBufAllocatorL.java
@@ -48,6 +48,9 @@ public class PooledByteBufAllocatorL {
empty = new UnsafeDirectLittleEndian(new
DuplicatedByteBuf(Unpooled.EMPTY_BUFFER));
}
+ /**
+ * Returns a {@linkplain io.netty.buffer.UnsafeDirectLittleEndian} of the
given size.
+ */
public UnsafeDirectLittleEndian allocate(int size) {
try {
return allocator.directBuffer(size, Integer.MAX_VALUE);
diff --git
a/java/memory/src/main/java/org/apache/arrow/memory/BaseAllocator.java
b/java/memory/src/main/java/org/apache/arrow/memory/BaseAllocator.java
index 857f6c9..34613b4 100644
--- a/java/memory/src/main/java/org/apache/arrow/memory/BaseAllocator.java
+++ b/java/memory/src/main/java/org/apache/arrow/memory/BaseAllocator.java
@@ -31,6 +31,12 @@ import io.netty.buffer.ArrowBuf;
import io.netty.buffer.UnsafeDirectLittleEndian;
import io.netty.util.internal.OutOfDirectMemoryError;
+/**
+ * A base-class that implements all functionality of {@linkplain
BufferAllocator}s.
+ *
+ * <p>The class is abstract to enforce usage of {@linkplain
RootAllocator}/{@linkplain ChildAllocator}
+ * facades.
+ */
public abstract class BaseAllocator extends Accountant implements
BufferAllocator {
public static final String DEBUG_ALLOCATOR = "arrow.memory.debug.allocator";
@@ -690,6 +696,10 @@ public abstract class BaseAllocator extends Accountant
implements BufferAllocato
}
}
+ /**
+ * Implementation of {@link AllocationReservation} that supports
+ * history tracking under {@linkplain #DEBUG} is true.
+ */
public class Reservation implements AllocationReservation {
private final HistoricalLog historicalLog;
@@ -697,6 +707,12 @@ public abstract class BaseAllocator extends Accountant
implements BufferAllocato
private boolean used = false;
private boolean closed = false;
+ /**
+ * Creates a new reservation.
+ *
+ * <p>If {@linkplain #DEBUG} is true this will capture a historical
+ * log of events relevant to this Reservation.
+ */
public Reservation() {
if (DEBUG) {
historicalLog = new HistoricalLog("Reservation[allocator[%s], %d]",
name, System
diff --git
a/java/memory/src/main/java/org/apache/arrow/memory/BoundsChecking.java
b/java/memory/src/main/java/org/apache/arrow/memory/BoundsChecking.java
index e9b5f38..a1a6e97 100644
--- a/java/memory/src/main/java/org/apache/arrow/memory/BoundsChecking.java
+++ b/java/memory/src/main/java/org/apache/arrow/memory/BoundsChecking.java
@@ -17,6 +17,13 @@
package org.apache.arrow.memory;
+/**
+ * Configuration class to determine if bounds checking should be turned on or
off.
+ *
+ * <p>Bounds checking is on by default. To disable it you must set the system
properties
+ * "arrow.enable_unsafe_memory_access" and "drill.enable_unsafe_memory_access"
to "true"
+ * and disable java assertions.
+ */
public class BoundsChecking {
public static final boolean BOUNDS_CHECKING_ENABLED;
diff --git
a/java/memory/src/main/java/org/apache/arrow/memory/OutOfMemoryException.java
b/java/memory/src/main/java/org/apache/arrow/memory/OutOfMemoryException.java
index 25efc11..d7e4786 100644
---
a/java/memory/src/main/java/org/apache/arrow/memory/OutOfMemoryException.java
+++
b/java/memory/src/main/java/org/apache/arrow/memory/OutOfMemoryException.java
@@ -17,7 +17,13 @@
package org.apache.arrow.memory;
-
+/**
+ * Indicates memory could not be allocated for Arrow buffers.
+ *
+ * <p>This is different from {@linkplain OutOfMemoryError} which indicates the
JVM
+ * is out of memory. This error indicates that static limit of one of Arrow's
+ * allocators (e.g. {@linkplain BaseAllocator}) has been exceeded.
+ */
public class OutOfMemoryException extends RuntimeException {
static final org.slf4j.Logger logger =
org.slf4j.LoggerFactory.getLogger(OutOfMemoryException
diff --git
a/java/memory/src/main/java/org/apache/arrow/memory/RootAllocator.java
b/java/memory/src/main/java/org/apache/arrow/memory/RootAllocator.java
index e8a5080..b6fefd7 100644
--- a/java/memory/src/main/java/org/apache/arrow/memory/RootAllocator.java
+++ b/java/memory/src/main/java/org/apache/arrow/memory/RootAllocator.java
@@ -20,8 +20,9 @@ package org.apache.arrow.memory;
import org.apache.arrow.util.VisibleForTesting;
/**
- * The root allocator for using direct memory inside a Drillbit. Supports
creating a
- * tree of descendant child allocators.
+ * A root allocator for using direct memory for Arrow Vectors/Arrays. Supports
creating a
+ * tree of descendant child allocators to facilitate better instrumentation of
memory
+ * allocations.
*/
public class RootAllocator extends BaseAllocator {
diff --git a/java/memory/src/test/java/io/netty/buffer/TestArrowBuf.java
b/java/memory/src/test/java/io/netty/buffer/TestArrowBuf.java
index feb7c44..1187015 100644
--- a/java/memory/src/test/java/io/netty/buffer/TestArrowBuf.java
+++ b/java/memory/src/test/java/io/netty/buffer/TestArrowBuf.java
@@ -38,7 +38,8 @@ public class TestArrowBuf {
public static void beforeClass() {
allocator = new RootAllocator(MAX_ALLOCATION);
}
-
+
+ /** Ensure the allocator is closed. */
@AfterClass
public static void afterClass() {
if (allocator != null) {
