diff --git a/common/src/main/java/io/netty/util/Attribute.java b/common/src/main/java/io/netty/util/Attribute.java index e773c8b4ae..b104a16a72 100644 --- a/common/src/main/java/io/netty/util/Attribute.java +++ b/common/src/main/java/io/netty/util/Attribute.java @@ -15,11 +15,42 @@ */ package io.netty.util; +/** + * An attribute which allows to store an value reference. It may be updated atomically and so is thread-safe. + * + * @param the type of the value it holds. + */ public interface Attribute { + /** + * Returns the current value, which may be {@code null} + */ T get(); + + /** + * Sets the value + */ void set(T value); + + /** + * Atomically sets to the given value and returns the old value which may be {@code null} if non was set before. + */ T getAndSet(T value); + + /** + * Atomically sets to the given value if this {@link Attribute} does not contain a value at the moment. + * If it was not possible to set the value as it contains a value it will just return the current value. + */ T setIfAbsent(T value); + + /** + * Atomically sets the value to the given updated value if the current value == the expected value. + * If it the set was successful it returns {@code true} otherwise {@code false}. + */ boolean compareAndSet(T oldValue, T newValue); + + /** + * Remove the current value which is stored in this {@link Attribute}, which means after this call {@link #get()} + * will return {@code null}. + */ void remove(); } diff --git a/common/src/main/java/io/netty/util/AttributeKey.java b/common/src/main/java/io/netty/util/AttributeKey.java index 5d1ca83564..f658a6e9fb 100644 --- a/common/src/main/java/io/netty/util/AttributeKey.java +++ b/common/src/main/java/io/netty/util/AttributeKey.java @@ -18,10 +18,22 @@ package io.netty.util; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; +/** + * Key which can be used to access {@link Attribute} out of the {@link AttributeMap}. Be aware that it is not be + * possible to have multiple keys with the same name. + * + * + * @param the type of the {@link Attribute} which can be accessed via this {@link AttributeKey}. + */ public final class AttributeKey extends UniqueName { private static final ConcurrentMap names = new ConcurrentHashMap(); + /** + * Create a new instance + * + * @param name the name under which the {@link AttributeKey} will be registered + */ public AttributeKey(String name) { super(names, name); } diff --git a/common/src/main/java/io/netty/util/AttributeMap.java b/common/src/main/java/io/netty/util/AttributeMap.java index 12c09c3eef..baa06a5a31 100644 --- a/common/src/main/java/io/netty/util/AttributeMap.java +++ b/common/src/main/java/io/netty/util/AttributeMap.java @@ -15,6 +15,15 @@ */ package io.netty.util; +/** + * Holds {@link Attribute}s which can be accessed via {@link AttributeKey}. + * + * Implementations must be Thread-safe. + */ public interface AttributeMap { + /** + * Get the {@link Attribute} for the given {@link AttributeKey}. This method will never return null, but may return + * an {@link AttributeKey} which has not value set yet. + */ Attribute attr(AttributeKey key); } diff --git a/common/src/main/java/io/netty/util/DefaultAttributeMap.java b/common/src/main/java/io/netty/util/DefaultAttributeMap.java index 648c2994b9..c3a380de34 100644 --- a/common/src/main/java/io/netty/util/DefaultAttributeMap.java +++ b/common/src/main/java/io/netty/util/DefaultAttributeMap.java @@ -19,6 +19,10 @@ import java.util.IdentityHashMap; import java.util.Map; import java.util.concurrent.atomic.AtomicReference; +/** + * Default {@link AttributeMap} implementation which use simple synchronization to keep the memory overhead + * as low as possible. + */ public class DefaultAttributeMap implements AttributeMap { // Initialize lazily to reduce memory consumption. @@ -41,7 +45,7 @@ public class DefaultAttributeMap implements AttributeMap { return attr; } - private class DefaultAttribute extends AtomicReference implements Attribute { + private static final class DefaultAttribute extends AtomicReference implements Attribute { private static final long serialVersionUID = -2661411462200283011L; diff --git a/common/src/main/java/io/netty/util/UniqueName.java b/common/src/main/java/io/netty/util/UniqueName.java index 4de43bd60f..755d85f9ac 100644 --- a/common/src/main/java/io/netty/util/UniqueName.java +++ b/common/src/main/java/io/netty/util/UniqueName.java @@ -60,6 +60,7 @@ public class UniqueName implements Comparable { * * @param args arguments to validate */ + @SuppressWarnings("unused") protected void validateArgs(Object... args) { // Subclasses will override. } diff --git a/common/src/main/java/io/netty/util/internal/DetectionUtil.java b/common/src/main/java/io/netty/util/internal/DetectionUtil.java index 5b3e66d671..05657b11cf 100644 --- a/common/src/main/java/io/netty/util/internal/DetectionUtil.java +++ b/common/src/main/java/io/netty/util/internal/DetectionUtil.java @@ -118,14 +118,24 @@ public final class DetectionUtil { return IS_ROOT; } + /** + * Return {@code true} if {@link sun.misc.Unsafe} was found on the classpath and can be used. + */ public static boolean hasUnsafe() { return HAS_UNSAFE; } + /** + * Return the version of Java under which this library is used. + */ public static int javaVersion() { return JAVA_VERSION; } + /** + * Return {@code true} if direct buffers can be freed using an optimized way and so memory footprint will be very + * small. + */ public static boolean canFreeDirectBuffer() { return CAN_FREE_DIRECT_BUFFER; } diff --git a/common/src/main/java/io/netty/util/internal/SharedResourceMisuseDetector.java b/common/src/main/java/io/netty/util/internal/SharedResourceMisuseDetector.java index a31eb07a01..98ebfa9da6 100644 --- a/common/src/main/java/io/netty/util/internal/SharedResourceMisuseDetector.java +++ b/common/src/main/java/io/netty/util/internal/SharedResourceMisuseDetector.java @@ -24,7 +24,7 @@ import java.util.concurrent.atomic.AtomicLong; /** * Warn when user creates too many instances to avoid {@link OutOfMemoryError}. */ -public class SharedResourceMisuseDetector { +public final class SharedResourceMisuseDetector { private static final int MAX_ACTIVE_INSTANCES = 256; private static final InternalLogger logger = @@ -41,6 +41,9 @@ public class SharedResourceMisuseDetector { this.type = type; } + /** + * Increase the use-count of the instance + */ public void increase() { if (activeInstances.incrementAndGet() > MAX_ACTIVE_INSTANCES) { if (logger.isWarnEnabled()) { @@ -55,6 +58,9 @@ public class SharedResourceMisuseDetector { } } + /** + * Decrease the use-count of the instance + */ public void decrease() { activeInstances.decrementAndGet(); } diff --git a/common/src/main/java/io/netty/util/internal/Signal.java b/common/src/main/java/io/netty/util/internal/Signal.java index 0c77118f8a..bdf22e37e3 100644 --- a/common/src/main/java/io/netty/util/internal/Signal.java +++ b/common/src/main/java/io/netty/util/internal/Signal.java @@ -21,6 +21,11 @@ import io.netty.util.UniqueName; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; +/** + * A special {@link Error} which is used to signal some state via an {@link Error}. + * + * This instance will have no stacktrace filled or any cause set to safe the overhead. + */ public final class Signal extends Error { private static final long serialVersionUID = -221145131122459977L; @@ -30,11 +35,20 @@ public final class Signal extends Error { private final UniqueName uname; + /** + * Create a new instance + * + * @param name the name under which it is registered + */ public Signal(String name) { super(name); uname = new UniqueName(map, name); } + /** + * Check if the given {@link Signal} is the same as this instance. If not an {@link IllegalStateException} will + * be thrown. + */ public void expect(Signal signal) { if (this != signal) { throw new IllegalStateException("unexpected signal: " + signal);