/*
    * Copyright 2012 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 io.netty.channel.group;
  
  import io.netty.channel.Channel;
  import io.netty.channel.ChannelFuture;
  import io.netty.channel.ChannelHandler;
  import io.netty.channel.ChannelHandlerContext;
  import io.netty.util.concurrent.Future;
  import io.netty.util.concurrent.GenericFutureListener;
  
  import java.util.Iterator;
  
  /**
   * 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(GenericFutureListener)} to {@link #await()}</h3>
   *
   * It is recommended to prefer {@link #addListener(GenericFutureListener)} to
   * {@link #await()} wherever possible to get notified when I/O operations are
   * done and to do any follow-up tasks.
   * <p>
   * {@link #addListener(GenericFutureListener)} 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.  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, ShutdownMessage msg) {
   *     {@link ChannelGroup} allChannels = MyServer.getAllChannels();
   *     {@link ChannelGroupFuture} future = allChannels.close();
   *     future.awaitUninterruptibly();
   *     // Perform post-shutdown operation
   *     // ...
   *
   * }
   *
   * // GOOD
   * {@code @Override}
   * public void messageReceived(ChannelHandlerContext ctx, ShutdownMessage msg) {
   *     {@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.
  */
 public interface ChannelGroupFuture extends Future<Void>, Iterable<ChannelFuture> {
 
     /**
      * Returns the {@link ChannelGroup} which is associated with this future.
      */
     ChannelGroup group();
 
     /**
      * 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 all I/O operations associated with
      * this future were successful without any failure.
      */
     @Override
     boolean isSuccess();
 
     @Override
     ChannelGroupException cause();
 
     /**
      * 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 the I/O operations associated with
      * this future have failed partially with some success.
      */
     boolean isPartialFailure();
 
     @Override
     ChannelGroupFuture addListener(GenericFutureListener<? extends Future<? super Void>> listener);
 
     @Override
     ChannelGroupFuture addListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);
 
     @Override
     ChannelGroupFuture removeListener(GenericFutureListener<? extends Future<? super Void>> listener);
 
     @Override
     ChannelGroupFuture removeListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);
 
     @Override
     ChannelGroupFuture await() throws InterruptedException;
 
     @Override
     ChannelGroupFuture awaitUninterruptibly();
 
     @Override
     ChannelGroupFuture syncUninterruptibly();
 
     @Override
     ChannelGroupFuture sync() throws InterruptedException;
 
     /**
      * 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.
      */
     @Override
     Iterator<ChannelFuture> iterator();
 }