Interface ChannelFuture
-
- All Superinterfaces:
Future<java.lang.Void>
,java.util.concurrent.Future<java.lang.Void>
- All Known Subinterfaces:
ChannelProgressiveFuture
,ChannelProgressivePromise
,ChannelPromise
- All Known Implementing Classes:
DefaultChannelProgressivePromise
,DefaultChannelPromise
,DelegatingChannelPromiseNotifier
,VoidChannelPromise
public interface ChannelFuture extends Future<java.lang.Void>
The result of an asynchronousChannel
I/O operation.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
ChannelFuture
instance which gives you the information about the result or status of the I/O operation.A
ChannelFuture
is either uncompleted or completed. 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.+---------------------------+ | 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 | +---------------------------+
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 addChannelFutureListener
s so you can get notified when the I/O operation is completed.Prefer
It is recommended to preferaddListener(GenericFutureListener)
toawait()
addListener(GenericFutureListener)
toawait()
wherever possible to get notified when an I/O operation is done and to do any follow-up tasks.addListener(GenericFutureListener)
is non-blocking. It simply adds the specifiedChannelFutureListener
to theChannelFuture
, and I/O thread will notify the listeners when the I/O operation associated with the future is done.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.By contrast,
await()
is a blocking operation. Once called, the caller thread blocks until the operation is done. It is easier to implement a sequential logic withawait()
, 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.Do not call
await()
insideChannelHandler
The event handler methods in
ChannelHandler
are usually called by an I/O thread. Ifawait()
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 becauseawait()
can block the I/O operation it is waiting for, which is a dead lock.// BAD - NEVER DO THIS
@Override
public void channelRead(ChannelHandlerContext
ctx, Object msg) {ChannelFuture
future = ctx.channel().close(); future.awaitUninterruptibly(); // Perform post-closure operation // ... } // GOOD@Override
public void channelRead(ChannelHandlerContext
ctx, Object msg) {ChannelFuture
future = ctx.channel().close(); future.addListener(newChannelFutureListener
() { public void operationComplete(ChannelFuture
future) { // Perform post-closure operation // ... } }); }In spite of the disadvantages mentioned above, there are certainly the cases where it is more convenient to call
await()
. In such a case, please make sure you do not callawait()
in an I/O thread. Otherwise,BlockingOperationException
will be raised to prevent a dead lock.Do not confuse I/O timeout and await timeout
The timeout value you specify withFuture.await(long)
,Future.await(long, TimeUnit)
,Future.awaitUninterruptibly(long)
, orFuture.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:// BAD - NEVER DO THIS
Bootstrap
b = ...;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 } // GOODBootstrap
b = ...; // Configure the connect timeout option. b.option(ChannelOption
.CONNECT_TIMEOUT_MILLIS, 10000);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 }
-
-
Method Summary
All Methods Instance Methods Abstract Methods Modifier and Type Method Description ChannelFuture
addListener(GenericFutureListener<? extends Future<? super java.lang.Void>> listener)
Adds the specified listener to this future.ChannelFuture
addListeners(GenericFutureListener<? extends Future<? super java.lang.Void>>... listeners)
Adds the specified listeners to this future.ChannelFuture
await()
Waits for this future to be completed.ChannelFuture
awaitUninterruptibly()
Waits for this future to be completed without interruption.Channel
channel()
Returns a channel where the I/O operation associated with this future takes place.boolean
isVoid()
Returnstrue
if thisChannelFuture
is a void future and so not allow to call any of the following methods:addListener(GenericFutureListener)
addListeners(GenericFutureListener[])
await()
Future.await(long, TimeUnit)
()}Future.await(long)
()}awaitUninterruptibly()
sync()
syncUninterruptibly()
ChannelFuture
removeListener(GenericFutureListener<? extends Future<? super java.lang.Void>> listener)
Removes the first occurrence of the specified listener from this future.ChannelFuture
removeListeners(GenericFutureListener<? extends Future<? super java.lang.Void>>... listeners)
Removes the first occurrence for each of the listeners from this future.ChannelFuture
sync()
Waits for this future until it is done, and rethrows the cause of the failure if this future failed.ChannelFuture
syncUninterruptibly()
Waits for this future until it is done, and rethrows the cause of the failure if this future failed.-
Methods inherited from interface io.netty.util.concurrent.Future
await, await, awaitUninterruptibly, awaitUninterruptibly, cancel, cause, getNow, isCancellable, isSuccess
-
-
-
-
Method Detail
-
channel
Channel channel()
Returns a channel where the I/O operation associated with this future takes place.
-
addListener
ChannelFuture addListener(GenericFutureListener<? extends Future<? super java.lang.Void>> listener)
Description copied from interface:Future
Adds the specified listener to this future. The specified listener is notified when this future is done. If this future is already completed, the specified listener is notified immediately.- Specified by:
addListener
in interfaceFuture<java.lang.Void>
-
addListeners
ChannelFuture addListeners(GenericFutureListener<? extends Future<? super java.lang.Void>>... listeners)
Description copied from interface:Future
Adds the specified listeners to this future. The specified listeners are notified when this future is done. If this future is already completed, the specified listeners are notified immediately.- Specified by:
addListeners
in interfaceFuture<java.lang.Void>
-
removeListener
ChannelFuture removeListener(GenericFutureListener<? extends Future<? super java.lang.Void>> listener)
Description copied from interface:Future
Removes the first occurrence of the specified listener from this future. The specified listener is no longer notified when this future is done. If the specified listener is not associated with this future, this method does nothing and returns silently.- Specified by:
removeListener
in interfaceFuture<java.lang.Void>
-
removeListeners
ChannelFuture removeListeners(GenericFutureListener<? extends Future<? super java.lang.Void>>... listeners)
Description copied from interface:Future
Removes the first occurrence for each of the listeners from this future. The specified listeners are no longer notified when this future is done. If the specified listeners are not associated with this future, this method does nothing and returns silently.- Specified by:
removeListeners
in interfaceFuture<java.lang.Void>
-
sync
ChannelFuture sync() throws java.lang.InterruptedException
Description copied from interface:Future
Waits for this future until it is done, and rethrows the cause of the failure if this future failed.
-
syncUninterruptibly
ChannelFuture syncUninterruptibly()
Description copied from interface:Future
Waits for this future until it is done, and rethrows the cause of the failure if this future failed.- Specified by:
syncUninterruptibly
in interfaceFuture<java.lang.Void>
-
await
ChannelFuture await() throws java.lang.InterruptedException
Description copied from interface:Future
Waits for this future to be completed.
-
awaitUninterruptibly
ChannelFuture awaitUninterruptibly()
Description copied from interface:Future
Waits for this future to be completed without interruption. This method catches anInterruptedException
and discards it silently.- Specified by:
awaitUninterruptibly
in interfaceFuture<java.lang.Void>
-
isVoid
boolean isVoid()
Returnstrue
if thisChannelFuture
is a void future and so not allow to call any of the following methods:
-
-