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.
This commit is contained in:
Jakob Buchgraber 2015-02-17 12:20:37 -08:00 committed by Trustin Lee
parent 88954c022c
commit 93bcc6bbde
4 changed files with 70 additions and 50 deletions

View File

@ -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
*/

View File

@ -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(...).

View File

@ -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.
*/

View File

@ -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}.