From 2710af1b8a1a0a55e0109b42df4fd065be5d089e Mon Sep 17 00:00:00 2001 From: Norman Maurer Date: Tue, 28 Aug 2012 02:10:17 +0200 Subject: [PATCH] More javadocs --- .../netty/channel/DefaultEventExecutor.java | 5 ++++ .../java/io/netty/channel/EventExecutor.java | 28 +++++++++++++++++++ .../io/netty/channel/EventExecutorGroup.java | 6 ++++ .../java/io/netty/channel/EventLoopGroup.java | 17 +++++++++++ .../channel/SingleThreadEventExecutor.java | 4 +++ .../channel/socket/nio/NioEventLoop.java | 5 ++++ .../channel/socket/oio/OioEventLoop.java | 5 ++++ 7 files changed, 70 insertions(+) diff --git a/transport/src/main/java/io/netty/channel/DefaultEventExecutor.java b/transport/src/main/java/io/netty/channel/DefaultEventExecutor.java index 1dfae962f7..5ca5c5c261 100644 --- a/transport/src/main/java/io/netty/channel/DefaultEventExecutor.java +++ b/transport/src/main/java/io/netty/channel/DefaultEventExecutor.java @@ -17,6 +17,11 @@ package io.netty.channel; import java.util.concurrent.ThreadFactory; +/** + * Default {@link SingleThreadEventExecutor} implementation which just execute all submitted task in a + * serial fashion + * + */ class DefaultEventExecutor extends SingleThreadEventExecutor { DefaultEventExecutor( diff --git a/transport/src/main/java/io/netty/channel/EventExecutor.java b/transport/src/main/java/io/netty/channel/EventExecutor.java index 27d200737c..4653b5137b 100644 --- a/transport/src/main/java/io/netty/channel/EventExecutor.java +++ b/transport/src/main/java/io/netty/channel/EventExecutor.java @@ -17,8 +17,36 @@ package io.netty.channel; import java.util.concurrent.ScheduledExecutorService; +/** + * The {@link EventExecutor} is a special {@link ScheduledExecutorService} which comes + * with some handy methods to see if a {@link Thread} is executed in a event loop. + * Beside this it also extends the {@link EventExecutorGroup} to allow a generic way to + * access methods. + * + */ public interface EventExecutor extends EventExecutorGroup, ScheduledExecutorService { + + /** + * Returns a reference to itself. + */ + @Override + EventExecutor next(); + + /** + * Return the {@link EventExecutorGroup} which is the parent of this {@link EventExecutor}, + * or null if it has no parent + + */ EventExecutorGroup parent(); + + /** + * Calls {@link #inEventLoop(Thread)} with {@link Thread#currentThread()} as argument + */ boolean inEventLoop(); + + /** + * Return true if the given {@link Thread} is executed in the event loop, + * false otherwise. + */ boolean inEventLoop(Thread thread); } diff --git a/transport/src/main/java/io/netty/channel/EventExecutorGroup.java b/transport/src/main/java/io/netty/channel/EventExecutorGroup.java index c7d5c72618..382a83f50f 100644 --- a/transport/src/main/java/io/netty/channel/EventExecutorGroup.java +++ b/transport/src/main/java/io/netty/channel/EventExecutorGroup.java @@ -18,6 +18,12 @@ package io.netty.channel; import java.util.concurrent.ExecutorService; import java.util.concurrent.TimeUnit; +/** + * The {@link EventExecutorGroup} is responsible to provide {@link EventExecutor}'s to use via its + * {@link #next()} method. Beside this it also is responsible to handle their live-cycle and allows + * to shut them down in a global fashion. + * + */ public interface EventExecutorGroup { /** diff --git a/transport/src/main/java/io/netty/channel/EventLoopGroup.java b/transport/src/main/java/io/netty/channel/EventLoopGroup.java index 48fcd5cd3f..16cc4e5084 100644 --- a/transport/src/main/java/io/netty/channel/EventLoopGroup.java +++ b/transport/src/main/java/io/netty/channel/EventLoopGroup.java @@ -15,10 +15,27 @@ */ package io.netty.channel; +/** + * Special {@link EventExecutorGroup} which allows to register {@link Channel}'s that get + * processed for later selection during the event loop. + * + */ public interface EventLoopGroup extends EventExecutorGroup { + /** + * Return the next {@link EventLoop} to use + */ @Override EventLoop next(); + /** + * Register a {@link Channel} with this {@link EventLoop}. The returned {@link ChannelFuture} + * will get notified once the registration was complete. + */ ChannelFuture register(Channel channel); + + /** + * Register a {@link Channel} with this {@link EventLoop}. The passed {@link ChannelFuture} + * will get notified once the registration was complete and also will get returned. + */ ChannelFuture register(Channel channel, ChannelFuture future); } diff --git a/transport/src/main/java/io/netty/channel/SingleThreadEventExecutor.java b/transport/src/main/java/io/netty/channel/SingleThreadEventExecutor.java index a250d55cc4..7715825311 100644 --- a/transport/src/main/java/io/netty/channel/SingleThreadEventExecutor.java +++ b/transport/src/main/java/io/netty/channel/SingleThreadEventExecutor.java @@ -34,6 +34,10 @@ import java.util.concurrent.Semaphore; import java.util.concurrent.ThreadFactory; import java.util.concurrent.TimeUnit; +/** + * Abstract base class for {@link EventExecutor}'s that execute all its submitted tasks in a single thread. + * + */ public abstract class SingleThreadEventExecutor extends AbstractExecutorService implements EventExecutor { private static final InternalLogger logger = diff --git a/transport/src/main/java/io/netty/channel/socket/nio/NioEventLoop.java b/transport/src/main/java/io/netty/channel/socket/nio/NioEventLoop.java index 598c30c25c..670d43df14 100644 --- a/transport/src/main/java/io/netty/channel/socket/nio/NioEventLoop.java +++ b/transport/src/main/java/io/netty/channel/socket/nio/NioEventLoop.java @@ -37,6 +37,11 @@ import java.util.concurrent.ConcurrentLinkedQueue; import java.util.concurrent.ThreadFactory; import java.util.concurrent.atomic.AtomicBoolean; +/** + * {@link SingleThreadEventLoop} implementation which register the {@link Channel}'s to a + * {@link Selector} and so does the multi-plexing of these in the event loop. + * + */ final class NioEventLoop extends SingleThreadEventLoop { /** diff --git a/transport/src/main/java/io/netty/channel/socket/oio/OioEventLoop.java b/transport/src/main/java/io/netty/channel/socket/oio/OioEventLoop.java index 5492769af9..12f85b3d09 100644 --- a/transport/src/main/java/io/netty/channel/socket/oio/OioEventLoop.java +++ b/transport/src/main/java/io/netty/channel/socket/oio/OioEventLoop.java @@ -21,6 +21,11 @@ import io.netty.channel.ChannelFutureListener; import io.netty.channel.SingleThreadEventLoop; +/** + * {@link SingleThreadEventLoop} which is used to handle OIO {@link Channel}'s. So in general there will be + * one {@link OioEventLoop} per {@link Channel}. + * + */ class OioEventLoop extends SingleThreadEventLoop { private final OioEventLoopGroup parent;