From 93bcc6bbdef53e9249802e1bba72aca06f90ad45 Mon Sep 17 00:00:00 2001 From: Jakob Buchgraber Date: Tue, 17 Feb 2015 12:20:37 -0800 Subject: [PATCH] Document nEventLoops=0 in (Nio|Default|Epoll)EventLoopGroups. Motivation: When setting nEventLoops to zero in the MultithreadedEventLoopGroup constructor the EventLoopGroup chooses the number of EventLoops and Threads to use for you. We want to make use of this behaviour internally and thus we would like to document it as a part of the official API, so that we can rely on it. Modifications: Document the behaviour when setting nEventLoops to zero. Fix several spelling / sloppiness mistakes in the documentation. Result: nEventLoops=0 is now documented as a part of the official API. The quality of the documentation is improved. --- .../MultithreadEventExecutorGroup.java | 13 ++++--- .../channel/epoll/EpollEventLoopGroup.java | 36 +++++++++++------- .../netty/channel/DefaultEventLoopGroup.java | 37 ++++++++++--------- .../netty/channel/nio/NioEventLoopGroup.java | 34 ++++++++++------- 4 files changed, 70 insertions(+), 50 deletions(-) diff --git a/common/src/main/java/io/netty/util/concurrent/MultithreadEventExecutorGroup.java b/common/src/main/java/io/netty/util/concurrent/MultithreadEventExecutorGroup.java index 6d3c242482..b3b4123211 100644 --- a/common/src/main/java/io/netty/util/concurrent/MultithreadEventExecutorGroup.java +++ b/common/src/main/java/io/netty/util/concurrent/MultithreadEventExecutorGroup.java @@ -38,10 +38,11 @@ public abstract class MultithreadEventExecutorGroup extends AbstractEventExecuto /** * @param nEventExecutors the number of {@link EventExecutor}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventExecutor}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * If {@code executorServiceFactory} is {@code null} this number will also be + * the parallelism requested from the default {@link Executor}. It is generally + * advised for the number of {@link EventExecutor}s and the number of + * {@link Thread}s used by the {@code executorServiceFactory} to lie close + * together. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the default * should be used. * @param args arguments which will passed to each {@link #newChild(Executor, Object...)} call. @@ -58,9 +59,9 @@ public abstract class MultithreadEventExecutorGroup extends AbstractEventExecuto /** * @param nEventExecutors the number of {@link EventExecutor}s that will be used by this instance. * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventExecutor}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executor} to lie close together. * @param executor the {@link Executor} to use, or {@code null} if the default should be used. * @param args arguments which will passed to each {@link #newChild(Executor, Object...)} call */ diff --git a/transport-native-epoll/src/main/java/io/netty/channel/epoll/EpollEventLoopGroup.java b/transport-native-epoll/src/main/java/io/netty/channel/epoll/EpollEventLoopGroup.java index 8487354bb7..46a68a1cb7 100644 --- a/transport-native-epoll/src/main/java/io/netty/channel/epoll/EpollEventLoopGroup.java +++ b/transport-native-epoll/src/main/java/io/netty/channel/epoll/EpollEventLoopGroup.java @@ -31,7 +31,7 @@ import java.util.concurrent.Executor; public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { /** - * Create a new instance that uses twice as many {@link EventLoop}s as there processors/cores + * Create a new instance that uses twice as many {@link EventLoop}s as there are processors/cores * available, as well as the default {@link Executor}. * * @see io.netty.util.concurrent.DefaultExecutorServiceFactory @@ -46,9 +46,9 @@ public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { * @see io.netty.util.concurrent.DefaultExecutorServiceFactory * * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventLoop}s and the number of {@link Thread}s used by the + * This will also be the parallelism requested from the default {@link Executor}. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #EpollEventLoopGroup()}. */ public EpollEventLoopGroup(int nEventLoops) { this(nEventLoops, (Executor) null); @@ -57,9 +57,11 @@ public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #EpollEventLoopGroup()}. * @param executor the {@link Executor} to use, or {@code null} if the default should be used. */ @SuppressWarnings("deprecation") @@ -69,10 +71,12 @@ public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * If {@code executorServiceFactory} is {@code null} this number will also be the parallelism + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executorServiceFactory} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #EpollEventLoopGroup()}. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the * default should be used. */ @@ -84,9 +88,11 @@ public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #EpollEventLoopGroup()}. * @param executor the {@link Executor} to use, or {@code null} if the default should be used. * @param maxEventsAtOnce the maximum number of epoll events to handle per epollWait(...). * @@ -100,10 +106,12 @@ public final class EpollEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * If {@code executorServiceFactory} is {@code null} this number will also be the parallelism + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executorServiceFactory} to lie very close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #EpollEventLoopGroup()}. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the default * should be used. * @param maxEventsAtOnce the maximum number of epoll events to handle per epollWait(...). diff --git a/transport/src/main/java/io/netty/channel/DefaultEventLoopGroup.java b/transport/src/main/java/io/netty/channel/DefaultEventLoopGroup.java index 5701bf5c9b..d6c4dd23fb 100644 --- a/transport/src/main/java/io/netty/channel/DefaultEventLoopGroup.java +++ b/transport/src/main/java/io/netty/channel/DefaultEventLoopGroup.java @@ -25,7 +25,7 @@ import java.util.concurrent.Executor; public class DefaultEventLoopGroup extends MultithreadEventLoopGroup { /** - * Create a new instance that uses twice as many {@link EventLoop}s as there processors/cores + * Create a new instance that uses twice as many {@link EventLoop}s as there are processors/cores * available, as well as the default {@link Executor}. * * @see io.netty.util.concurrent.DefaultExecutorServiceFactory @@ -35,34 +35,37 @@ public class DefaultEventLoopGroup extends MultithreadEventLoopGroup { } /** - * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. + * This will also be the parallelism requested from the default {@link Executor}. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #DefaultEventLoopGroup()}. */ public DefaultEventLoopGroup(int nEventLoops) { this(nEventLoops, (Executor) null); } /** - * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. - * @param executor the {@link Executor} to use, or {@code null} if the default should be used. + * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. + * If {@code executor} is {@code null} this number will also be the parallelism + * requested from the default {@link Executor}. It is generally advised for the number + * of {@link EventLoop}s and the number of {@link Thread}s used by the + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #DefaultEventLoopGroup()}. + * @param executor the {@link Executor} to use, or {@code null} if the default should be used. */ public DefaultEventLoopGroup(int nEventLoops, Executor executor) { super(nEventLoops, executor); } /** - * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. + * If {@code executorServiceFactory} is {@code null} this number will also be the parallelism + * requested from the default {@link Executor}. It is generally advised for the number + * of {@link EventLoop}s and the number of {@link Thread}s used by the + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #DefaultEventLoopGroup()}. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the default * should be used. */ diff --git a/transport/src/main/java/io/netty/channel/nio/NioEventLoopGroup.java b/transport/src/main/java/io/netty/channel/nio/NioEventLoopGroup.java index b79cf34530..5102bd5ddc 100644 --- a/transport/src/main/java/io/netty/channel/nio/NioEventLoopGroup.java +++ b/transport/src/main/java/io/netty/channel/nio/NioEventLoopGroup.java @@ -31,7 +31,7 @@ import java.util.concurrent.Executor; public class NioEventLoopGroup extends MultithreadEventLoopGroup { /** - * Create a new instance that uses twice as many {@link EventLoop}s as there processors/cores + * Create a new instance that uses twice as many {@link EventLoop}s as there are processors/cores * available, as well as the default {@link Executor} and the {@link SelectorProvider} which * is returned by {@link SelectorProvider#provider()}. * @@ -48,9 +48,9 @@ public class NioEventLoopGroup extends MultithreadEventLoopGroup { * @see io.netty.util.concurrent.DefaultExecutorServiceFactory * * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number - * of {@link EventLoop}s and the number of {@link Thread}s used by the + * This will also be the parallelism requested from the default {@link Executor}. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #NioEventLoopGroup()}. */ public NioEventLoopGroup(int nEventLoops) { this(nEventLoops, (Executor) null); @@ -62,9 +62,11 @@ public class NioEventLoopGroup extends MultithreadEventLoopGroup { * * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #NioEventLoopGroup()}. * @param executor the {@link Executor} to use, or {@code null} if the default should be used. */ public NioEventLoopGroup(int nEventLoops, Executor executor) { @@ -76,10 +78,12 @@ public class NioEventLoopGroup extends MultithreadEventLoopGroup { * {@link SelectorProvider#provider()}. * * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * If {@code executorServiceFactory} is {@code null} this number will also be the parallelism + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executorServiceFactory} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #NioEventLoopGroup()}. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the default * should be used. */ @@ -90,9 +94,11 @@ public class NioEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. * If {@code executor} is {@code null} this number will also be the parallelism - * requested from the default executor. It is generally advised for the number + * requested from the default {@link Executor}. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executor} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #NioEventLoopGroup()}. * @param executor the {@link Executor} to use, or {@code null} if the default should be used. * @param selectorProvider the {@link SelectorProvider} to use. This value must not be {@code null}. */ @@ -102,10 +108,12 @@ public class NioEventLoopGroup extends MultithreadEventLoopGroup { /** * @param nEventLoops the number of {@link EventLoop}s that will be used by this instance. - * If {@code executor} is {@code null} this number will also be the parallelism + * If {@code executorServiceFactory} is {@code null} this number will also be the parallelism * requested from the default executor. It is generally advised for the number * of {@link EventLoop}s and the number of {@link Thread}s used by the - * {@code executor} to lie very close together. + * {@code executorServiceFactory} to lie close together. + * If set to {@code 0} the behaviour is the same as documented in + * {@link #NioEventLoopGroup()}. * @param executorServiceFactory the {@link ExecutorServiceFactory} to use, or {@code null} if the * default should be used. * @param selectorProvider the {@link SelectorProvider} to use. This value must not be {@code null}.