6e840d8e62
- fix the formatting of the diagram in ChannelFuture's javadoc - update external link in AutobahnServer - fix various spelling issues
213 lines
8.8 KiB
Java
213 lines
8.8 KiB
Java
/*
|
|
* 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();
|
|
|
|
/**
|
|
* Returns {@code true} if this {@link ChannelFuture} is a void future and so not allow to call any of the
|
|
* following methods:
|
|
* <ul>
|
|
* <li>{@link #addListener(GenericFutureListener)}</li>
|
|
* <li>{@link #addListeners(GenericFutureListener[])}</li>
|
|
* <li>{@link #await()}</li>
|
|
* <li>{@link #await(long, TimeUnit)} ()}</li>
|
|
* <li>{@link #await(long)} ()}</li>
|
|
* <li>{@link #awaitUninterruptibly()}</li>
|
|
* <li>{@link #sync()}</li>
|
|
* <li>{@link #syncUninterruptibly()}</li>
|
|
* </ul>
|
|
*/
|
|
boolean isVoid();
|
|
}
|