Package io.netty.handler.flush

Class FlushConsolidationHandler

java.lang.Object

io.netty.channel.ChannelHandlerAdapter

io.netty.channel.ChannelInboundHandlerAdapter

io.netty.channel.ChannelDuplexHandler

io.netty.handler.flush.FlushConsolidationHandler

All Implemented Interfaces:

ChannelHandler, ChannelInboundHandler, ChannelOutboundHandler

public class FlushConsolidationHandler
extends ChannelDuplexHandler

ChannelDuplexHandler which consolidates Channel.flush() / ChannelHandlerContext.flush() operations (which also includes Channel.writeAndFlush(Object) / Channel.writeAndFlush(Object, ChannelPromise) and ChannelOutboundInvoker.writeAndFlush(Object) / ChannelOutboundInvoker.writeAndFlush(Object, ChannelPromise)).

Flush operations are generally speaking expensive as these may trigger a syscall on the transport level. Thus it is in most cases (where write latency can be traded with throughput) a good idea to try to minimize flush operations as much as possible.

If a read loop is currently ongoing, flush(ChannelHandlerContext) will not be passed on to the next ChannelOutboundHandler in the ChannelPipeline, as it will pick up any pending flushes when channelReadComplete(ChannelHandlerContext) is triggered. If no read loop is ongoing, the behavior depends on the consolidateWhenNoReadInProgress constructor argument:

• if false, flushes are passed on to the next handler directly;
• if true, the invocation of the next handler is submitted as a separate task on the event loop. Under high throughput, this gives the opportunity to process other flushes before the task gets executed, thus batching multiple flushes into one.

If explicitFlushAfterFlushes is reached the flush will be forwarded as well (whether while in a read loop, or while batching outside of a read loop).

If the Channel becomes non-writable it will also try to execute any pending flush operations.

The FlushConsolidationHandler should be put as first ChannelHandler in the ChannelPipeline to have the best effect.

Nested Class Summary

Nested classes/interfaces inherited from interface io.netty.channel.ChannelHandler

ChannelHandler.Sharable

Field Summary

Fields

Modifier and Type	Field	Description
static int	DEFAULT_EXPLICIT_FLUSH_AFTER_FLUSHES	The default number of flushes after which a flush will be forwarded to downstream handlers (whether while in a read loop, or while batching outside of a read loop).

Constructor Summary

Constructors

Constructor	Description
FlushConsolidationHandler()	Create new instance which explicit flush after 256 pending flush operations at the latest.
FlushConsolidationHandler(int explicitFlushAfterFlushes)	Create new instance which doesn't consolidate flushes when no read is in progress.
FlushConsolidationHandler(int explicitFlushAfterFlushes, boolean consolidateWhenNoReadInProgress)	Create new instance.

Method Summary

Modifier and Type	Method	Description
void	channelRead(ChannelHandlerContext ctx, java.lang.Object msg)	Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	channelReadComplete(ChannelHandlerContext ctx)	Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	channelWritabilityChanged(ChannelHandlerContext ctx)	Calls ChannelHandlerContext.fireChannelWritabilityChanged() to forward to the next ChannelInboundHandler in the ChannelPipeline.
void	close(ChannelHandlerContext ctx, ChannelPromise promise)	Calls ChannelOutboundInvoker.close(ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline.
void	disconnect(ChannelHandlerContext ctx, ChannelPromise promise)	Calls ChannelOutboundInvoker.disconnect(ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline.
void	exceptionCaught(ChannelHandlerContext ctx, java.lang.Throwable cause)	Calls ChannelHandlerContext.fireExceptionCaught(Throwable) to forward to the next ChannelHandler in the ChannelPipeline.
void	flush(ChannelHandlerContext ctx)	Calls ChannelHandlerContext.flush() to forward to the next ChannelOutboundHandler in the ChannelPipeline.
void	handlerAdded(ChannelHandlerContext ctx)	Do nothing by default, sub-classes may override this method.
void	handlerRemoved(ChannelHandlerContext ctx)	Do nothing by default, sub-classes may override this method.

Methods inherited from class io.netty.channel.ChannelDuplexHandler

bind, connect, deregister, read, write

Methods inherited from class io.netty.channel.ChannelInboundHandlerAdapter

channelActive, channelInactive, channelRegistered, channelUnregistered, userEventTriggered

Methods inherited from class io.netty.channel.ChannelHandlerAdapter

ensureNotSharable, isSharable

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_EXPLICIT_FLUSH_AFTER_FLUSHES

public static final int DEFAULT_EXPLICIT_FLUSH_AFTER_FLUSHES

The default number of flushes after which a flush will be forwarded to downstream handlers (whether while in a read loop, or while batching outside of a read loop).

See Also:

Constant Field Values

Constructor Detail

FlushConsolidationHandler

public FlushConsolidationHandler()

Create new instance which explicit flush after 256 pending flush operations at the latest.

FlushConsolidationHandler

public FlushConsolidationHandler(int explicitFlushAfterFlushes)

Create new instance which doesn't consolidate flushes when no read is in progress.

Parameters:

explicitFlushAfterFlushes - the number of flushes after which an explicit flush will be done.

FlushConsolidationHandler

public FlushConsolidationHandler(int explicitFlushAfterFlushes,
                                 boolean consolidateWhenNoReadInProgress)

Create new instance.

Parameters:

explicitFlushAfterFlushes - the number of flushes after which an explicit flush will be done.

consolidateWhenNoReadInProgress - whether to consolidate flushes even when no read loop is currently ongoing.

Method Detail

handlerAdded

public void handlerAdded(ChannelHandlerContext ctx)
                  throws java.lang.Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerAdded in interface ChannelHandler

Overrides:

handlerAdded in class ChannelHandlerAdapter

Throws:

java.lang.Exception

flush

public void flush(ChannelHandlerContext ctx)
           throws java.lang.Exception

Description copied from class: ChannelDuplexHandler

Calls ChannelHandlerContext.flush() to forward to the next ChannelOutboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

flush in interface ChannelOutboundHandler

Overrides:

flush in class ChannelDuplexHandler

Parameters:

ctx - the ChannelHandlerContext for which the flush operation is made

Throws:

java.lang.Exception - thrown if an error occurs

channelReadComplete

public void channelReadComplete(ChannelHandlerContext ctx)
                         throws java.lang.Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelReadComplete() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelReadComplete in interface ChannelInboundHandler

Overrides:

channelReadComplete in class ChannelInboundHandlerAdapter

Throws:

java.lang.Exception

channelRead

public void channelRead(ChannelHandlerContext ctx,
                        java.lang.Object msg)
                 throws java.lang.Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelRead(Object) to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelRead in interface ChannelInboundHandler

Overrides:

channelRead in class ChannelInboundHandlerAdapter

Throws:

java.lang.Exception

exceptionCaught

public void exceptionCaught(ChannelHandlerContext ctx,
                            java.lang.Throwable cause)
                     throws java.lang.Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireExceptionCaught(Throwable) to forward to the next ChannelHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

exceptionCaught in interface ChannelHandler

Specified by:

exceptionCaught in interface ChannelInboundHandler

Overrides:

exceptionCaught in class ChannelInboundHandlerAdapter

Throws:

java.lang.Exception

disconnect

public void disconnect(ChannelHandlerContext ctx,
                       ChannelPromise promise)
                throws java.lang.Exception

Description copied from class: ChannelDuplexHandler

Calls ChannelOutboundInvoker.disconnect(ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

disconnect in interface ChannelOutboundHandler

Overrides:

disconnect in class ChannelDuplexHandler

Parameters:

ctx - the ChannelHandlerContext for which the disconnect operation is made

promise - the ChannelPromise to notify once the operation completes

Throws:

java.lang.Exception - thrown if an error occurs

close

public void close(ChannelHandlerContext ctx,
                  ChannelPromise promise)
           throws java.lang.Exception

Description copied from class: ChannelDuplexHandler

Calls ChannelOutboundInvoker.close(ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

close in interface ChannelOutboundHandler

Overrides:

close in class ChannelDuplexHandler

Parameters:

ctx - the ChannelHandlerContext for which the close operation is made

promise - the ChannelPromise to notify once the operation completes

Throws:

java.lang.Exception - thrown if an error occurs

channelWritabilityChanged

public void channelWritabilityChanged(ChannelHandlerContext ctx)
                               throws java.lang.Exception

Description copied from class: ChannelInboundHandlerAdapter

Calls ChannelHandlerContext.fireChannelWritabilityChanged() to forward to the next ChannelInboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Specified by:

channelWritabilityChanged in interface ChannelInboundHandler

Overrides:

channelWritabilityChanged in class ChannelInboundHandlerAdapter

Throws:

java.lang.Exception

handlerRemoved

public void handlerRemoved(ChannelHandlerContext ctx)
                    throws java.lang.Exception

Description copied from class: ChannelHandlerAdapter

Do nothing by default, sub-classes may override this method.

Specified by:

handlerRemoved in interface ChannelHandler

Overrides:

handlerRemoved in class ChannelHandlerAdapter

Throws:

java.lang.Exception