Package io.netty.handler.flush

Class FlushConsolidationHandler

  • All Implemented Interfaces:
    io.netty.channel.ChannelHandler, io.netty.channel.ChannelInboundHandler, io.netty.channel.ChannelOutboundHandler
    public class FlushConsolidationHandler
extends io.netty.channel.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

        io.netty.channel.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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void channelRead​(io.netty.channel.ChannelHandlerContext ctx, Object msg)  
      void channelReadComplete​(io.netty.channel.ChannelHandlerContext ctx)  
      void channelWritabilityChanged​(io.netty.channel.ChannelHandlerContext ctx)  
      void close​(io.netty.channel.ChannelHandlerContext ctx, io.netty.channel.ChannelPromise promise)  
      void disconnect​(io.netty.channel.ChannelHandlerContext ctx, io.netty.channel.ChannelPromise promise)  
      void exceptionCaught​(io.netty.channel.ChannelHandlerContext ctx, Throwable cause)  
      void flush​(io.netty.channel.ChannelHandlerContext ctx)  
      void handlerAdded​(io.netty.channel.ChannelHandlerContext ctx)  
      void handlerRemoved​(io.netty.channel.ChannelHandlerContext ctx)  

      • 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

    • 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​(io.netty.channel.ChannelHandlerContext ctx)
                  throws Exception
        Specified by:
        handlerAdded in interface io.netty.channel.ChannelHandler
        Overrides:
        handlerAdded in class io.netty.channel.ChannelHandlerAdapter
        Throws:
        Exception

      • flush

        public void flush​(io.netty.channel.ChannelHandlerContext ctx)
           throws Exception
        Specified by:
        flush in interface io.netty.channel.ChannelOutboundHandler
        Overrides:
        flush in class io.netty.channel.ChannelDuplexHandler
        Throws:
        Exception

      • channelReadComplete

        public void channelReadComplete​(io.netty.channel.ChannelHandlerContext ctx)
                         throws Exception
        Specified by:
        channelReadComplete in interface io.netty.channel.ChannelInboundHandler
        Overrides:
        channelReadComplete in class io.netty.channel.ChannelInboundHandlerAdapter
        Throws:
        Exception

      • channelRead

        public void channelRead​(io.netty.channel.ChannelHandlerContext ctx,
                        Object msg)
                 throws Exception
        Specified by:
        channelRead in interface io.netty.channel.ChannelInboundHandler
        Overrides:
        channelRead in class io.netty.channel.ChannelInboundHandlerAdapter
        Throws:
        Exception

      • exceptionCaught

        public void exceptionCaught​(io.netty.channel.ChannelHandlerContext ctx,
                            Throwable cause)
                     throws Exception
        Specified by:
        exceptionCaught in interface io.netty.channel.ChannelHandler
        Specified by:
        exceptionCaught in interface io.netty.channel.ChannelInboundHandler
        Overrides:
        exceptionCaught in class io.netty.channel.ChannelInboundHandlerAdapter
        Throws:
        Exception

      • disconnect

        public void disconnect​(io.netty.channel.ChannelHandlerContext ctx,
                       io.netty.channel.ChannelPromise promise)
                throws Exception
        Specified by:
        disconnect in interface io.netty.channel.ChannelOutboundHandler
        Overrides:
        disconnect in class io.netty.channel.ChannelDuplexHandler
        Throws:
        Exception

      • close

        public void close​(io.netty.channel.ChannelHandlerContext ctx,
                  io.netty.channel.ChannelPromise promise)
           throws Exception
        Specified by:
        close in interface io.netty.channel.ChannelOutboundHandler
        Overrides:
        close in class io.netty.channel.ChannelDuplexHandler
        Throws:
        Exception

      • channelWritabilityChanged

        public void channelWritabilityChanged​(io.netty.channel.ChannelHandlerContext ctx)
                               throws Exception
        Specified by:
        channelWritabilityChanged in interface io.netty.channel.ChannelInboundHandler
        Overrides:
        channelWritabilityChanged in class io.netty.channel.ChannelInboundHandlerAdapter
        Throws:
        Exception

      • handlerRemoved

        public void handlerRemoved​(io.netty.channel.ChannelHandlerContext ctx)
                    throws Exception
        Specified by:
        handlerRemoved in interface io.netty.channel.ChannelHandler
        Overrides:
        handlerRemoved in class io.netty.channel.ChannelHandlerAdapter
        Throws:
        Exception