查看本类的 API文档回源码主页

   /*
    * 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;
  
  import io.netty.bootstrap.Bootstrap;
  import io.netty.util.concurrent.BlockingOperationException;
  import io.netty.util.concurrent.Future;
  import io.netty.util.concurrent.GenericFutureListener;
  
  import java.util.concurrent.TimeUnit;
  
  
  /**
   * The result of an asynchronous {@link Channel} I/O operation.
   * <p>
   * All I/O operations in Netty are asynchronous.  It means any I/O calls will
   * return immediately with no guarantee that the requested I/O operation has
   * been completed at the end of the call.  Instead, you will be returned with
   * a {@link ChannelFuture} instance which gives you the information about the
   * result or status of the I/O operation.
   * <p>
   * A {@link ChannelFuture} is either <em>uncompleted</em> or <em>completed</em>.
   * When an I/O operation begins, a new future object is created.  The new future
   * is uncompleted initially - it is neither succeeded, failed, nor cancelled
   * because the I/O operation is not finished yet.  If the I/O operation is
   * finished either successfully, with failure, or by cancellation, the future is
   * marked as completed with more specific information, such as the cause of the
   * failure.  Please note that even failure and cancellation belong to the
   * completed state.
   * <pre>
   *                                      +---------------------------+
   *                                      | Completed successfully    |
   *                                      +---------------------------+
   *                                 +---->      isDone() = true      |
   * +--------------------------+    |    |   isSuccess() = true      |
   * |        Uncompleted       |    |    +===========================+
   * +--------------------------+    |    | Completed with failure    |
   * |      isDone() = false    |    |    +---------------------------+
   * |   isSuccess() = false    |----+---->      isDone() = true      |
   * | isCancelled() = false    |    |    |       cause() = non-null  |
   * |       cause() = null     |    |    +===========================+
   * +--------------------------+    |    | Completed by cancellation |
   *                                 |    +---------------------------+
   *                                 +---->      isDone() = true      |
   *                                      | isCancelled() = true      |
   *                                      +---------------------------+
   * </pre>
   *
   * Various methods are provided to let you check if the I/O operation has been
   * completed, wait for the completion, and retrieve the result of the I/O
   * operation. It also allows you to add {@link ChannelFutureListener}s so you
   * can get notified when the I/O operation is 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 an I/O operation is
   * done and to do any follow-up tasks.
   * <p>
   * {@link #addListener(GenericFutureListener)} is non-blocking.  It simply adds
   * the specified {@link ChannelFutureListener} to the {@link ChannelFuture}, and
   * I/O thread will notify the listeners when the I/O operation associated with
   * the future is done.  {@link ChannelFutureListener} 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 the operation is done.  It is easier to implement
   * a sequential logic with {@link #await()}, but the caller thread blocks
   * unnecessarily until the I/O operation is 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} are usually 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 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 channelRead({@link ChannelHandlerContext} ctx, Object msg) {
   *     {@link ChannelFuture} future = ctx.channel().close();
  *     future.awaitUninterruptibly();
  *     // Perform post-closure operation
  *     // ...
  * }
  *
  * // GOOD
  * {@code @Override}
  * public void channelRead({@link ChannelHandlerContext} ctx, Object msg) {
  *     {@link ChannelFuture} future = ctx.channel().close();
  *     future.addListener(new {@link ChannelFutureListener}() {
  *         public void operationComplete({@link ChannelFuture} 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 BlockingOperationException} will be raised to prevent a dead lock.
  *
  * <h3>Do not confuse I/O timeout and await timeout</h3>
  *
  * The timeout value you specify with {@link #await(long)},
  * {@link #await(long, TimeUnit)}, {@link #awaitUninterruptibly(long)}, or
  * {@link #awaitUninterruptibly(long, TimeUnit)} are not related with I/O
  * timeout at all.  If an I/O operation times out, the future will be marked as
  * 'completed with failure,' as depicted in the diagram above.  For example,
  * connect timeout should be configured via a transport-specific option:
  * <pre>
  * // BAD - NEVER DO THIS
  * {@link Bootstrap} b = ...;
  * {@link ChannelFuture} f = b.connect(...);
  * f.awaitUninterruptibly(10, TimeUnit.SECONDS);
  * if (f.isCancelled()) {
  *     // Connection attempt cancelled by user
  * } else if (!f.isSuccess()) {
  *     // You might get a NullPointerException here because the future
  *     // might not be completed yet.
  *     f.cause().printStackTrace();
  * } else {
  *     // Connection established successfully
  * }
  *
  * // GOOD
  * {@link Bootstrap} b = ...;
  * // Configure the connect timeout option.
  * <b>b.option({@link ChannelOption}.CONNECT_TIMEOUT_MILLIS, 10000);</b>
  * {@link ChannelFuture} f = b.connect(...);
  * f.awaitUninterruptibly();
  *
  * // Now we are sure the future is completed.
  * assert f.isDone();
  *
  * if (f.isCancelled()) {
  *     // Connection attempt cancelled by user
  * } else if (!f.isSuccess()) {
  *     f.cause().printStackTrace();
  * } else {
  *     // Connection established successfully
  * }
  * </pre>
  */
 public interface ChannelFuture extends Future<Void> {
 
     /**
      * Returns a channel where the I/O operation associated with this
      * future takes place.
      */
     Channel channel();
 
     @Override
     ChannelFuture addListener(GenericFutureListener<? extends Future<? super Void>> listener);
 
     @Override
     ChannelFuture addListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);
 
     @Override
     ChannelFuture removeListener(GenericFutureListener<? extends Future<? super Void>> listener);
 
     @Override
     ChannelFuture removeListeners(GenericFutureListener<? extends Future<? super Void>>... listeners);
 
     @Override
     ChannelFuture sync() throws InterruptedException;
 
     @Override
     ChannelFuture syncUninterruptibly();
 
     @Override
     ChannelFuture await() throws InterruptedException;
 
     @Override
     ChannelFuture awaitUninterruptibly();
 }