From 090306b2b955808724bc711fc8e53d6439f416dc Mon Sep 17 00:00:00 2001
From: Ludovic Orban
Date: Wed, 15 Jun 2022 09:16:52 +0200
Subject: [PATCH] #8161 improve javadoc and mod doc
Signed-off-by: Ludovic Orban
---
.../jetty/io/AbstractByteBufferPool.java | 8 +++-
.../eclipse/jetty/io/ArrayByteBufferPool.java | 9 +++-
.../io/ArrayRetainableByteBufferPool.java | 44 +++++++++++++++++++
.../modules/retainablebytebufferpool.mod | 8 ++--
4 files changed, 61 insertions(+), 8 deletions(-)
diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/AbstractByteBufferPool.java b/jetty-io/src/main/java/org/eclipse/jetty/io/AbstractByteBufferPool.java
index 03237c035ea1..759935f4bda0 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/AbstractByteBufferPool.java
+++ b/jetty-io/src/main/java/org/eclipse/jetty/io/AbstractByteBufferPool.java
@@ -22,6 +22,10 @@
import org.eclipse.jetty.util.annotation.ManagedObject;
import org.eclipse.jetty.util.annotation.ManagedOperation;
+/**
+ * The {@code maxHeapMemory} and {@code maxDirectMemory} default heuristic is to use {@link Runtime#maxMemory()}
+ * divided by 4.
+ */
@ManagedObject
abstract class AbstractByteBufferPool implements ByteBufferPool
{
@@ -37,8 +41,8 @@ abstract class AbstractByteBufferPool implements ByteBufferPool
*
* @param factor the capacity factor
* @param maxQueueLength the maximum ByteBuffer queue length
- * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic.
- * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic.
+ * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic
*/
protected AbstractByteBufferPool(int factor, int maxQueueLength, long maxHeapMemory, long maxDirectMemory)
{
diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayByteBufferPool.java b/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayByteBufferPool.java
index 0cdb05235316..02a6130c9aee 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayByteBufferPool.java
+++ b/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayByteBufferPool.java
@@ -34,6 +34,8 @@
* Given a capacity {@code factor} of 1024, the first array element holds a queue of ByteBuffers
* each of capacity 1024, the second array element holds a queue of ByteBuffers each of capacity
* 2048, and so on.
+ * The {@code maxHeapMemory} and {@code maxDirectMemory} default heuristic is to use {@link Runtime#maxMemory()}
+ * divided by 4.
*/
@ManagedObject
public class ArrayByteBufferPool extends AbstractByteBufferPool implements Dumpable
@@ -48,6 +50,7 @@ public class ArrayByteBufferPool extends AbstractByteBufferPool implements Dumpa
/**
* Creates a new ArrayByteBufferPool with a default configuration.
+ * Both {@code maxHeapMemory} and {@code maxDirectMemory} default to 0 to use default heuristic.
*/
public ArrayByteBufferPool()
{
@@ -56,6 +59,7 @@ public ArrayByteBufferPool()
/**
* Creates a new ArrayByteBufferPool with the given configuration.
+ * Both {@code maxHeapMemory} and {@code maxDirectMemory} default to 0 to use default heuristic.
*
* @param minCapacity the minimum ByteBuffer capacity
* @param factor the capacity factor
@@ -68,6 +72,7 @@ public ArrayByteBufferPool(int minCapacity, int factor, int maxCapacity)
/**
* Creates a new ArrayByteBufferPool with the given configuration.
+ * Both {@code maxHeapMemory} and {@code maxDirectMemory} default to 0 to use default heuristic.
*
* @param minCapacity the minimum ByteBuffer capacity
* @param factor the capacity factor
@@ -86,8 +91,8 @@ public ArrayByteBufferPool(int minCapacity, int factor, int maxCapacity, int max
* @param factor the capacity factor
* @param maxCapacity the maximum ByteBuffer capacity
* @param maxQueueLength the maximum ByteBuffer queue length
- * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic.
- * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic.
+ * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic
*/
public ArrayByteBufferPool(int minCapacity, int factor, int maxCapacity, int maxQueueLength, long maxHeapMemory, long maxDirectMemory)
{
diff --git a/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayRetainableByteBufferPool.java b/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayRetainableByteBufferPool.java
index e08f0e04f3ea..cf4c0e239bf4 100644
--- a/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayRetainableByteBufferPool.java
+++ b/jetty-io/src/main/java/org/eclipse/jetty/io/ArrayRetainableByteBufferPool.java
@@ -30,6 +30,15 @@
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
+/**
+ * A {@link RetainableByteBuffer} pool where RetainableByteBuffers are held in {@link Pool}s that are
+ * held in array elements.
+ * Given a capacity {@code factor} of 1024, the first array element holds a Pool of RetainableByteBuffers
+ * each of capacity 1024, the second array element holds a Pool of RetainableByteBuffers each of capacity
+ * 2048, and so on.
+ * The {@code maxHeapMemory} and {@code maxDirectMemory} default heuristic is to use {@link Runtime#maxMemory()}
+ * divided by 4.
+ */
@ManagedObject
public class ArrayRetainableByteBufferPool implements RetainableByteBufferPool, Dumpable
{
@@ -45,21 +54,56 @@ public class ArrayRetainableByteBufferPool implements RetainableByteBufferPool,
private final AtomicLong _currentDirectMemory = new AtomicLong();
private final Function _bucketIndexFor;
+ /**
+ * Creates a new ArrayRetainableByteBufferPool with a default configuration.
+ * Both {@code maxHeapMemory} and {@code maxDirectMemory} default to 0 to use default heuristic.
+ */
public ArrayRetainableByteBufferPool()
{
this(0, -1, -1, Integer.MAX_VALUE);
}
+ /**
+ * Creates a new ArrayRetainableByteBufferPool with the given configuration.
+ * Both {@code maxHeapMemory} and {@code maxDirectMemory} default to 0 to use default heuristic.
+ *
+ * @param minCapacity the minimum ByteBuffer capacity
+ * @param factor the capacity factor
+ * @param maxCapacity the maximum ByteBuffer capacity
+ * @param maxBucketSize the maximum number of ByteBuffers for each bucket
+ */
public ArrayRetainableByteBufferPool(int minCapacity, int factor, int maxCapacity, int maxBucketSize)
{
this(minCapacity, factor, maxCapacity, maxBucketSize, 0L, 0L);
}
+ /**
+ * Creates a new ArrayRetainableByteBufferPool with the given configuration.
+ *
+ * @param minCapacity the minimum ByteBuffer capacity
+ * @param factor the capacity factor
+ * @param maxCapacity the maximum ByteBuffer capacity
+ * @param maxBucketSize the maximum number of ByteBuffers for each bucket
+ * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ */
public ArrayRetainableByteBufferPool(int minCapacity, int factor, int maxCapacity, int maxBucketSize, long maxHeapMemory, long maxDirectMemory)
{
this(minCapacity, factor, maxCapacity, maxBucketSize, maxHeapMemory, maxDirectMemory, null, null);
}
+ /**
+ * Creates a new ArrayRetainableByteBufferPool with the given configuration.
+ *
+ * @param minCapacity the minimum ByteBuffer capacity
+ * @param factor the capacity factor
+ * @param maxCapacity the maximum ByteBuffer capacity
+ * @param maxBucketSize the maximum number of ByteBuffers for each bucket
+ * @param maxHeapMemory the max heap memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ * @param maxDirectMemory the max direct memory in bytes, -1 for unlimited memory or 0 to use default heuristic
+ * @param bucketIndexFor a {@link Function} that takes a capacity and returns a bucket index
+ * @param bucketCapacity a {@link Function} that takes a bucket index and returns a capacity
+ */
protected ArrayRetainableByteBufferPool(int minCapacity, int factor, int maxCapacity, int maxBucketSize, long maxHeapMemory, long maxDirectMemory,
Function bucketIndexFor, Function bucketCapacity)
{
diff --git a/jetty-server/src/main/config/modules/retainablebytebufferpool.mod b/jetty-server/src/main/config/modules/retainablebytebufferpool.mod
index 0199f061f808..1ce28212706f 100644
--- a/jetty-server/src/main/config/modules/retainablebytebufferpool.mod
+++ b/jetty-server/src/main/config/modules/retainablebytebufferpool.mod
@@ -2,7 +2,7 @@
Configures the RetainableByteBufferPool used by ServerConnectors.
[tags]
-retainableByteBufferPool
+retainablebytebufferpool
[xml]
etc/jetty-retainablebytebufferpool.xml
@@ -21,11 +21,11 @@ etc/jetty-retainablebytebufferpool.xml
## a capacity that is multiple of this factor.
#jetty.retainableByteBufferPool.factor=1024
-## Maximum size for each bucket.
+## Maximum number of ByteBuffers for each bucket.
#jetty.retainableByteBufferPool.maxBucketSize=2147483647
-## Maximum heap memory retainable by the pool (0 for heuristic, -1 for unlimited).
+## Maximum heap memory bytes retainable by the pool (0 for heuristic, -1 for unlimited).
#jetty.retainableByteBufferPool.maxHeapMemory=0
-## Maximum direct memory retainable by the pool (0 for heuristic, -1 for unlimited).
+## Maximum direct memory bytes retainable by the pool (0 for heuristic, -1 for unlimited).
#jetty.retainableByteBufferPool.maxDirectMemory=0