/*
* Copyright 2011 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
package org.jboss.netty.channel.group;
import java.util.Iterator;
import java.util.concurrent.TimeUnit;
import org.jboss.netty.channel.Channel;
import org.jboss.netty.channel.ChannelFuture;
import org.jboss.netty.channel.ChannelHandler;
import org.jboss.netty.channel.ChannelHandlerContext;
import org.jboss.netty.channel.ChannelPipeline;
import org.jboss.netty.channel.MessageEvent;
import org.jboss.netty.handler.execution.ExecutionHandler;
/**
* The result of an asynchronous {@link ChannelGroup} operation.
* {@link ChannelGroupFuture} is composed of {@link ChannelFuture}s which
* represent the outcome of the individual I/O operations that affect the
* {@link Channel}s in the {@link ChannelGroup}.
*
* <p>
* All I/O operations in {@link ChannelGroup} are asynchronous. It means any
* I/O calls will return immediately with no guarantee that the requested I/O
* operations have been completed at the end of the call. Instead, you will be
* returned with a {@link ChannelGroupFuture} instance which tells you when the
* requested I/O operations have succeeded, failed, or cancelled.
* <p>
* Various methods are provided to let you check if the I/O operations has been
* completed, wait for the completion, and retrieve the result of the I/O
* operation. It also allows you to add more than one
* {@link ChannelGroupFutureListener} so you can get notified when the I/O
* operation have been completed.
*
* <h3>Prefer {@link #addListener(ChannelGroupFutureListener)} to {@link #await()}</h3>
*
* It is recommended to prefer {@link #addListener(ChannelGroupFutureListener)} to
* {@link #await()} wherever possible to get notified when I/O operations are
* done and to do any follow-up tasks.
* <p>
* {@link #addListener(ChannelGroupFutureListener)} is non-blocking. It simply
* adds the specified {@link ChannelGroupFutureListener} to the
* {@link ChannelGroupFuture}, and I/O thread will notify the listeners when
* the I/O operations associated with the future is done.
* {@link ChannelGroupFutureListener} yields the best performance and resource
* utilization because it does not block at all, but it could be tricky to
* implement a sequential logic if you are not used to event-driven programming.
* <p>
* By contrast, {@link #await()} is a blocking operation. Once called, the
* caller thread blocks until all I/O operations are done. It is easier to
* implement a sequential logic with {@link #await()}, but the caller thread
* blocks unnecessarily until all I/O operations are done and there's relatively
* expensive cost of inter-thread notification. Moreover, there's a chance of
* dead lock in a particular circumstance, which is described below.
*
* <h3>Do not call {@link #await()} inside {@link ChannelHandler}</h3>
* <p>
* The event handler methods in {@link ChannelHandler} is often called by
* an I/O thread unless an {@link ExecutionHandler} is in the
* {@link ChannelPipeline}. If {@link #await()} is called by an event handler
* method, which is called by the I/O thread, the I/O operation it is waiting
* for might never be complete because {@link #await()} can block the I/O
* operation it is waiting for, which is a dead lock.
* <pre>
* // BAD - NEVER DO THIS
* {@code @Override}
* public void messageReceived({@link ChannelHandlerContext} ctx, {@link MessageEvent} e) {
* if (e.getMessage() instanceof ShutdownMessage) {
* {@link ChannelGroup} allChannels = MyServer.getAllChannels();
* {@link ChannelGroupFuture} future = allChannels.close();
* future.awaitUninterruptibly();
* // Perform post-shutdown operation
* // ...
* }
* }
*
* // GOOD
* {@code @Override}
* public void messageReceived(ChannelHandlerContext ctx, MessageEvent e) {
* if (e.getMessage() instanceof ShutdownMessage) {
* {@link ChannelGroup} allChannels = MyServer.getAllChannels();
* {@link ChannelGroupFuture} future = allChannels.close();
* future.addListener(new {@link ChannelGroupFutureListener}() {
* public void operationComplete({@link ChannelGroupFuture} future) {
* // Perform post-closure operation
* // ...
* }
* });
* }
* }
* </pre>
* <p>
* In spite of the disadvantages mentioned above, there are certainly the cases
* where it is more convenient to call {@link #await()}. In such a case, please
* make sure you do not call {@link #await()} in an I/O thread. Otherwise,
* {@link IllegalStateException} will be raised to prevent a dead lock.
* @apiviz.owns org.jboss.netty.channel.group.ChannelGroupFutureListener - - notifies
*/
public interface ChannelGroupFuture extends Iterable<ChannelFuture> {
/**
* Returns the {@link ChannelGroup} which is associated with this future.
*/
ChannelGroup getGroup();
/**
* Returns the {@link ChannelFuture} of the individual I/O operation which
* is associated with the {@link Channel} whose ID matches the specified
* integer.
*
* @return the matching {@link ChannelFuture} if found.
* {@code null} otherwise.
*/
ChannelFuture find(Integer channelId);
/**
* Returns the {@link ChannelFuture} of the individual I/O operation which
* is associated with the specified {@link Channel}.
*
* @return the matching {@link ChannelFuture} if found.
* {@code null} otherwise.
*/
ChannelFuture find(Channel channel);
/**
* Returns {@code true} if and only if this future is
* complete, regardless of whether the operation was successful, failed,
* or canceled.
*/
boolean isDone();
/**
* Returns {@code true} if and only if all I/O operations associated with
* this future were successful without any failure.
*/
boolean isCompleteSuccess();
/**
* Returns {@code true} if and only if the I/O operations associated with
* this future were partially successful with some failure.
*/
boolean isPartialSuccess();
/**
* Returns {@code true} if and only if all I/O operations associated with
* this future have failed without any success.
*/
boolean isCompleteFailure();
/**
* Returns {@code true} if and only if the I/O operations associated with
* this future have failed partially with some success.
*/
boolean isPartialFailure();
/**
* Adds the specified listener to this future. The
* specified listener is notified when this future is
* {@linkplain #isDone() done}. If this future is already
* completed, the specified listener is notified immediately.
*/
void addListener(ChannelGroupFutureListener listener);
/**
* Removes the specified listener from this future.
* The specified listener is no longer notified when this
* future is {@linkplain #isDone() done}. If this
* future is already completed, this method has no effect
* and returns silently.
*/
void removeListener(ChannelGroupFutureListener listener);
/**
* Waits for this future to be completed.
*
* @throws InterruptedException
* if the current thread was interrupted
*/
ChannelGroupFuture await() throws InterruptedException;
/**
* Waits for this future to be completed without
* interruption. This method catches an {@link InterruptedException} and
* discards it silently.
*/
ChannelGroupFuture awaitUninterruptibly();
/**
* Waits for this future to be completed within the
* specified time limit.
*
* @return {@code true} if and only if the future was completed within
* the specified time limit
*
* @throws InterruptedException
* if the current thread was interrupted
*/
boolean await(long timeout, TimeUnit unit) throws InterruptedException;
/**
* Waits for this future to be completed within the
* specified time limit.
*
* @return {@code true} if and only if the future was completed within
* the specified time limit
*
* @throws InterruptedException
* if the current thread was interrupted
*/
boolean await(long timeoutMillis) throws InterruptedException;
/**
* Waits for this future to be completed within the
* specified time limit without interruption. This method catches an
* {@link InterruptedException} and discards it silently.
*
* @return {@code true} if and only if the future was completed within
* the specified time limit
*/
boolean awaitUninterruptibly(long timeout, TimeUnit unit);
/**
* Waits for this future to be completed within the
* specified time limit without interruption. This method catches an
* {@link InterruptedException} and discards it silently.
*
* @return {@code true} if and only if the future was completed within
* the specified time limit
*/
boolean awaitUninterruptibly(long timeoutMillis);
/**
* Returns the {@link Iterator} that enumerates all {@link ChannelFuture}s
* which are associated with this future. Please note that the returned
* {@link Iterator} is is unmodifiable, which means a {@link ChannelFuture}
* cannot be removed from this future.
*/
Iterator<ChannelFuture> iterator();
}