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