org.jboss.netty.channel.group
接口 ChannelGroupFuture

所有超级接口：

java.lang.Iterable<ChannelFuture>

所有已知实现类：

DefaultChannelGroupFuture

public interface ChannelGroupFuture
extends java.lang.Iterable<ChannelFuture>

通道组异步操作的结果.ChannelGroupFuture是由ChannelFuture 组成.表示个别I/O操作影响通道组中的通道的结果.

通道组中所有I/O操作都是异步的.这意味着任何I/O操作立即返回,而不会保证I/O请求调用后就完成.而是会返回一个 ChannelGroupFuture实例来通知你请求成功,失败或取消结果.

它提供不同的方法让你检查I/O操作是否已经完成,等待完成,接收I/O操作结果.也允许你添加多个 ChannelGroupFutureListener以便当I/O操作完成你能收到通知.

使用 addListener(ChannelGroupFutureListener)比await()更好

建议优先使用addListener(ChannelGroupFutureListener),再使用await() ,因为不管在什么地方,当I/O操作完成你都可以收到通知,并执行后续任务.

addListener(ChannelGroupFutureListener)是非阻塞的.它简单的为 ChannelGroupFuture添加特定的ChannelGroupFutureListener ,并且当该future关联的I/O操作完成后I/O线程会通知这些监听器.由于它是不阻塞的,所以 ChannelGroupFutureListener 有最好的性能和资源利用率, 但是如果你不是使用事件驱动编程,它实现顺序逻辑就很棘手.

相比之下, await()是阻塞操作.一旦调用,调用线程会阻塞直到所有I/O操作完成为止.虽然使用await() 可以很简单的实现一个顺序逻辑 ,但是调用线程会不必要的阻塞直到所有I/O操作完成和相当昂贵的交互线程通知的开销.而且,在特别情况下还有可能会出现死锁,如下所描述.

别在ChannelHandler里面调用await()

ChannelHandler的事件处理方法会经常被I/O线程调用,除了ChannelPipeline里的 ExecutionHandler.如果await() 被一个I/O线程调用的事件处理方法调用,该I/O操作会是一个永远不会完成一直等待的操作,因为await() 会阻塞该I/O操作,所以是一个死锁.

 // BAD - 别这么做
 @Override
 public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
     if (e.getMessage() instanceof ShutdownMessage) {
         ChannelGroup allChannels = MyServer.getAllChannels();
         ChannelGroupFuture future = allChannels.close();
         future.awaitUninterruptibly();
         // Perform post-shutdown operation
         // ...
     }
 }
 
 // GOOD
 @Override
 public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
     if (e.getMessage() instanceof ShutdownMessage) {
         ChannelGroup allChannels = MyServer.getAllChannels();
         ChannelGroupFuture future = allChannels.close();
         future.addListener(new ChannelGroupFutureListener() {
             public void operationComplete(ChannelGroupFuture future) {
                 // Perform post-closure operation
                 // ...
             }
         });
     }
 }
 

尽管有以上提到的缺点,在某些情况下,调用await()会更方便.在这种情况下,请确保你没有在一个I/O线程里调用 await().否则,会抛出IllegalStateException异常以防止死锁.

方法摘要

void	addListener(ChannelGroupFutureListener listener) 添加指定监听器到该future.当该future完成 时该监听器会收到通知.如果该future已经完成,监听器会马上收到通知.
ChannelGroupFuture	await() 等该该future完成.
boolean	await(long timeoutMillis) 在指定的时间限制内等待future的完成.
boolean	await(long timeout, java.util.concurrent.TimeUnit unit) 在指定的时间限制内等待future的完成.
ChannelGroupFuture	awaitUninterruptibly() 等待该future完成.该方法会捕捉InterruptedException并安静丢弃.
boolean	awaitUninterruptibly(long timeoutMillis) 在指定的时间限制内等待future的完成.该方法会捕捉InterruptedException并丢弃异常.
boolean	awaitUninterruptibly(long timeout, java.util.concurrent.TimeUnit unit) 在指定的时间限制内等待future的完成.该方法会捕捉InterruptedException并丢弃异常.
ChannelFuture	find(Channel channel) 返回匹配指定Channel关联的有自己I/O操作的ChannelFuture.
ChannelFuture	find(java.lang.Integer channelId) 返回匹配指定ChannelID关联的有自己I/O操作的ChannelFuture.
ChannelGroup	getGroup() 返回该future关联的ChannelGroup.
boolean	isCompleteFailure() 只有该future关联的所有I/O操作失败才返回true.
boolean	isCompleteSuccess() 只有该future关联的所有I/O操作成功才返回true.
boolean	isDone() 只有当该future完成才返回true,不管操作是否成功、失败、或者取消.
boolean	isPartialFailure() 只有该future关联的I/O操作有部分失败才返回true.
boolean	isPartialSuccess() 只有该future关联的I/O操作有部分成功才返回true.
java.util.Iterator<ChannelFuture>	iterator() 返回枚举该future关联的所有ChannelFuture的Iterator.请注意返回的 Iterator是不可修改的,也就是说ChannelFuture不会被移除.
void	removeListener(ChannelGroupFutureListener listener) 移除指定的监听器.当该future完成 ,该监听器不再收到通知.如果该future已经完成,该方法不会有任何效果.

方法详细信息

getGroup

ChannelGroup getGroup()

返回该future关联的ChannelGroup.

find

ChannelFuture find(java.lang.Integer channelId)

返回匹配指定ChannelID关联的有自己I/O操作的ChannelFuture.

返回：

返回匹配的ChannelFuture.否则返回null.

find

ChannelFuture find(Channel channel)

返回匹配指定Channel关联的有自己I/O操作的ChannelFuture.

返回：

返回匹配的ChannelFuture.否则返回null.

isDone

boolean isDone()

只有当该future完成才返回true,不管操作是否成功、失败、或者取消.

isCompleteSuccess

boolean isCompleteSuccess()

只有该future关联的所有I/O操作成功才返回true.

isPartialSuccess

boolean isPartialSuccess()

只有该future关联的I/O操作有部分成功才返回true.

isCompleteFailure

boolean isCompleteFailure()

只有该future关联的所有I/O操作失败才返回true.

isPartialFailure

boolean isPartialFailure()

只有该future关联的I/O操作有部分失败才返回true.

addListener

void addListener(ChannelGroupFutureListener listener)

添加指定监听器到该future.当该future完成 时该监听器会收到通知.如果该future已经完成,监听器会马上收到通知.

removeListener

void removeListener(ChannelGroupFutureListener listener)

移除指定的监听器.当该future完成 ,该监听器不再收到通知.如果该future已经完成,该方法不会有任何效果.

await

ChannelGroupFuture await()
                         throws java.lang.InterruptedException

等该该future完成.

抛出：

java.lang.InterruptedException - 如果当前线程被打断则抛出异常

awaitUninterruptibly

ChannelGroupFuture awaitUninterruptibly()

等待该future完成.该方法会捕捉InterruptedException并安静丢弃.

await

boolean await(long timeout,
              java.util.concurrent.TimeUnit unit)
              throws java.lang.InterruptedException

在指定的时间限制内等待future的完成.

返回：

只有在指定时间限制内完成才返回true

抛出：

java.lang.InterruptedException - 如果当前线程被打断则抛出异常

await

boolean await(long timeoutMillis)
              throws java.lang.InterruptedException

在指定的时间限制内等待future的完成.

返回：

只有在指定时间限制内完成才返回true

抛出：

java.lang.InterruptedException - 如果当前线程被打断则抛出异常

awaitUninterruptibly

boolean awaitUninterruptibly(long timeout,
                             java.util.concurrent.TimeUnit unit)

在指定的时间限制内等待future的完成.该方法会捕捉InterruptedException并丢弃异常.

返回：

只有在指定时间限制内完成才返回true

awaitUninterruptibly

boolean awaitUninterruptibly(long timeoutMillis)

在指定的时间限制内等待future的完成.该方法会捕捉InterruptedException并丢弃异常.

返回：

只有在指定时间限制内完成才返回true

iterator

java.util.Iterator<ChannelFuture> iterator()

返回枚举该future关联的所有ChannelFuture的Iterator.请注意返回的 Iterator是不可修改的,也就是说ChannelFuture不会被移除.

指定者：

接口 java.lang.Iterable<ChannelFuture> 中的 iterator