Netty/Handler 4.1.107.Final · io.netty.handler.timeout.IdleStateHandler

Triggers an IdleStateEvent when a Channel has not performed read, write, or both operation for a while.

Supported idle states

Property	Meaning
`readerIdleTime`	an `IdleStateEvent` whose state is `IdleState#READER_IDLE` will be triggered when no read was performed for the specified period of time. Specify `0` to disable.
`writerIdleTime`	an `IdleStateEvent` whose state is `IdleState#WRITER_IDLE` will be triggered when no write was performed for the specified period of time. Specify `0` to disable.
`allIdleTime`	an `IdleStateEvent` whose state is `IdleState#ALL_IDLE` will be triggered when neither read nor write was performed for the specified period of time. Specify `0` to disable.

// An example that sends a ping message when there is no outbound traffic
// for 30 seconds.  The connection is closed when there is no inbound traffic
// for 60 seconds.

public class MyChannelInitializer extends ChannelInitializer<Channel> {
    @Override
    public void initChannel(Channel channel) {
        channel.pipeline().addLast("idleStateHandler", new IdleStateHandler(60, 30, 0));
        channel.pipeline().addLast("myHandler", new MyHandler());
    }
}

// Handler should handle the IdleStateEvent triggered by IdleStateHandler.
public class MyHandler extends ChannelDuplexHandler {
    @Override
    public void userEventTriggered(ChannelHandlerContext ctx, Object evt) throws Exception {
        if (evt instanceof IdleStateEvent) {
            IdleStateEvent e = (IdleStateEvent) evt;
            if (e.state() == IdleState.READER_IDLE) {
                ctx.close();
            } else if (e.state() == IdleState.WRITER_IDLE) {
                ctx.writeAndFlush(new PingMessage());
            }
        }
    }
}

ServerBootstrap bootstrap = ...;
...
bootstrap.childHandler(new MyChannelInitializer());
...

Nested and Inner Type Summary

Modifier and Type	Class and Description
private abstract static class	IdleStateHandler.AbstractIdleTask
private class	IdleStateHandler.AllIdleTimeoutTask
private class	IdleStateHandler.ReaderIdleTimeoutTask
private class	IdleStateHandler.WriterIdleTimeoutTask

Field Summary

Modifier and Type	Field and Description
private final long	allIdleTimeNanos
private Future<?>	allIdleTimeout
private boolean	firstAllIdleEvent
private boolean	firstReaderIdleEvent
private boolean	firstWriterIdleEvent
private long	lastChangeCheckTimeStamp
private long	lastFlushProgress
private int	lastMessageHashCode
private long	lastPendingWriteBytes
private long	lastReadTime
private long	lastWriteTime
private static final long	MIN_TIMEOUT_NANOS
private final boolean	observeOutput
private final long	readerIdleTimeNanos
private Future<?>	readerIdleTimeout
private boolean	reading
private static final byte	ST_DESTROYED
private static final byte	ST_INITIALIZED
private byte	state
private final ChannelFutureListener	writeListener
private final long	writerIdleTimeNanos
private Future<?>	writerIdleTimeout

Constructor Summary

Access	Constructor and Description
public	IdleStateHandler(int an `IdleStateEvent` whose state is `IdleState#READER_IDLE` will be triggered when no read was performed for the specified period of time. Specify `0` to disable. readerIdleTimeSeconds, int an `IdleStateEvent` whose state is `IdleState#WRITER_IDLE` will be triggered when no write was performed for the specified period of time. Specify `0` to disable. writerIdleTimeSeconds, int an `IdleStateEvent` whose state is `IdleState#ALL_IDLE` will be triggered when neither read nor write was performed for the specified period of time. Specify `0` to disable. allIdleTimeSeconds) Creates a new instance firing `IdleStateEvent`s.
public	IdleStateHandler(long readerIdleTime, long writerIdleTime, long allIdleTime, TimeUnit unit)
public	IdleStateHandler(boolean whether or not the consumption of `bytes` should be taken into consideration when assessing write idleness. The default is `false`. observeOutput, long an `IdleStateEvent` whose state is `IdleState#READER_IDLE` will be triggered when no read was performed for the specified period of time. Specify `0` to disable. readerIdleTime, long an `IdleStateEvent` whose state is `IdleState#WRITER_IDLE` will be triggered when no write was performed for the specified period of time. Specify `0` to disable. writerIdleTime, long an `IdleStateEvent` whose state is `IdleState#ALL_IDLE` will be triggered when neither read nor write was performed for the specified period of time. Specify `0` to disable. allIdleTime, TimeUnit the `TimeUnit` of `readerIdleTime`, `writeIdleTime`, and `allIdleTime` unit) Creates a new instance firing `IdleStateEvent`s.

Method Summary

Modifier and Type	Method and Description
public void	channelActive(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelActive. Implements io.netty.channel.ChannelInboundHandler.channelActive. Calls `ChannelHandlerContext#fireChannelActive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
protected void	channelIdle(ChannelHandlerContext ctx, IdleStateEvent evt) Is called when an `IdleStateEvent` should be fired.
public void	channelInactive(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Implements io.netty.channel.ChannelInboundHandler.channelInactive. Calls `ChannelHandlerContext#fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
public void	channelRead(ChannelHandlerContext ctx, Object msg) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Implements io.netty.channel.ChannelInboundHandler.channelRead. Calls `ChannelHandlerContext#fireChannelRead(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
public void	channelReadComplete(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Implements io.netty.channel.ChannelInboundHandler.channelReadComplete. Calls `ChannelHandlerContext#fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
public void	channelRegistered(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRegistered. Implements io.netty.channel.ChannelInboundHandler.channelRegistered. Calls `ChannelHandlerContext#fireChannelRegistered()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`.
private void	destroy()
public long	getAllIdleTimeInMillis() Return the allIdleTime that was given when instance this class in milliseconds.
public long	getReaderIdleTimeInMillis() Return the readerIdleTime that was given when instance this class in milliseconds.
public long	getWriterIdleTimeInMillis() Return the writerIdleTime that was given when instance this class in milliseconds.
public void	handlerAdded(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelHandlerAdapter.handlerAdded. Implements io.netty.channel.ChannelHandler.handlerAdded. Gets called after the `ChannelHandler` was added to the actual context and it's ready to handle events.
public void	handlerRemoved(ChannelHandlerContext ctx) Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved. Implements io.netty.channel.ChannelHandler.handlerRemoved. Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore.
private boolean	hasOutputChanged(ChannelHandlerContext ctx, boolean first) Returns `true` if and only if the `IdleStateHandler` was constructed with `observeOutput` enabled and there has been an observed change in the `ChannelOutboundBuffer` between two consecutive calls of this method.
private void	initialize(ChannelHandlerContext ctx)
private void	initOutputChanged(ChannelHandlerContext ctx)
protected IdleStateEvent	newIdleStateEvent(IdleState state, boolean first) Returns a `IdleStateEvent`.
public void	resetReadTimeout() Reset the read timeout.
public void	resetWriteTimeout() Reset the write timeout.
pack-priv Future<?>	schedule(ChannelHandlerContext ctx, Runnable task, long delay, TimeUnit unit) This method is visible for testing!
pack-priv long	ticksInNanos() This method is visible for testing!
public void	write(ChannelHandlerContext the `ChannelHandlerContext` for which the write operation is made ctx, Object the message to write msg, ChannelPromise the `ChannelPromise` to notify once the operation completes promise) Overrides io.netty.channel.ChannelDuplexHandler.write. Implements io.netty.channel.ChannelOutboundHandler.write. Calls `ChannelHandlerContext#write(Object, ChannelPromise)` to forward to the next `ChannelOutboundHandler` in the `ChannelPipeline`.

Inherited from io.netty.channel.ChannelDuplexHandler:: bind close connect deregister disconnect flush read

Field Detail

allIdleTimeNanos	back to summary
private final long allIdleTimeNanos

allIdleTimeout	back to summary
private Future<?> allIdleTimeout

firstAllIdleEvent	back to summary
private boolean firstAllIdleEvent

firstReaderIdleEvent	back to summary
private boolean firstReaderIdleEvent

firstWriterIdleEvent	back to summary
private boolean firstWriterIdleEvent

lastChangeCheckTimeStamp	back to summary
private long lastChangeCheckTimeStamp

lastFlushProgress	back to summary
private long lastFlushProgress

lastMessageHashCode	back to summary
private int lastMessageHashCode

lastPendingWriteBytes	back to summary
private long lastPendingWriteBytes

lastReadTime	back to summary
private long lastReadTime

lastWriteTime	back to summary
private long lastWriteTime

MIN_TIMEOUT_NANOS	back to summary
private static final long MIN_TIMEOUT_NANOS

observeOutput	back to summary
private final boolean observeOutput

readerIdleTimeNanos	back to summary
private final long readerIdleTimeNanos

readerIdleTimeout	back to summary
private Future<?> readerIdleTimeout

reading	back to summary
private boolean reading

ST_DESTROYED	back to summary
private static final byte ST_DESTROYED

ST_INITIALIZED	back to summary
private static final byte ST_INITIALIZED

state	back to summary
private byte state

writeListener	back to summary
private final ChannelFutureListener writeListener

writerIdleTimeNanos	back to summary
private final long writerIdleTimeNanos

writerIdleTimeout	back to summary
private Future<?> writerIdleTimeout

Constructor Detail

IdleStateHandler back to summary

IdleStateHandler	back to summary
public IdleStateHandler(int readerIdleTimeSeconds, int writerIdleTimeSeconds, int allIdleTimeSeconds) Creates a new instance firing `IdleStateEvent`s. Parameters readerIdleTimeSeconds:int an `IdleStateEvent` whose state is `IdleState#READER_IDLE` will be triggered when no read was performed for the specified period of time. Specify `0` to disable. writerIdleTimeSeconds:int an `IdleStateEvent` whose state is `IdleState#WRITER_IDLE` will be triggered when no write was performed for the specified period of time. Specify `0` to disable. allIdleTimeSeconds:int an `IdleStateEvent` whose state is `IdleState#ALL_IDLE` will be triggered when neither read nor write was performed for the specified period of time. Specify `0` to disable.

public IdleStateHandler(int readerIdleTimeSeconds, int writerIdleTimeSeconds, int allIdleTimeSeconds)

Creates a new instance firing IdleStateEvents.

Parameters

readerIdleTimeSeconds:int: an IdleStateEvent whose state is IdleState#READER_IDLE will be triggered when no read was performed for the specified period of time. Specify 0 to disable.
writerIdleTimeSeconds:int: an IdleStateEvent whose state is IdleState#WRITER_IDLE will be triggered when no write was performed for the specified period of time. Specify 0 to disable.
allIdleTimeSeconds:int: an IdleStateEvent whose state is IdleState#ALL_IDLE will be triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.

IdleStateHandler	back to summary
public IdleStateHandler(long readerIdleTime, long writerIdleTime, long allIdleTime, TimeUnit unit) See Also `IdleStateHandler(boolean, long, long, long, TimeUnit)`

IdleStateHandler back to summary

IdleStateHandler	back to summary
public IdleStateHandler(boolean observeOutput, long readerIdleTime, long writerIdleTime, long allIdleTime, TimeUnit unit) Creates a new instance firing `IdleStateEvent`s. Parameters observeOutput:boolean whether or not the consumption of `bytes` should be taken into consideration when assessing write idleness. The default is `false`. readerIdleTime:long an `IdleStateEvent` whose state is `IdleState#READER_IDLE` will be triggered when no read was performed for the specified period of time. Specify `0` to disable. writerIdleTime:long an `IdleStateEvent` whose state is `IdleState#WRITER_IDLE` will be triggered when no write was performed for the specified period of time. Specify `0` to disable. allIdleTime:long an `IdleStateEvent` whose state is `IdleState#ALL_IDLE` will be triggered when neither read nor write was performed for the specified period of time. Specify `0` to disable. unit:TimeUnit the `TimeUnit` of `readerIdleTime`, `writeIdleTime`, and `allIdleTime`

public IdleStateHandler(boolean observeOutput, long readerIdleTime, long writerIdleTime, long allIdleTime, TimeUnit unit)

Creates a new instance firing IdleStateEvents.

Parameters

observeOutput:boolean: whether or not the consumption of bytes should be taken into consideration when assessing write idleness. The default is false.
readerIdleTime:long: an IdleStateEvent whose state is IdleState#READER_IDLE will be triggered when no read was performed for the specified period of time. Specify 0 to disable.
writerIdleTime:long: an IdleStateEvent whose state is IdleState#WRITER_IDLE will be triggered when no write was performed for the specified period of time. Specify 0 to disable.
allIdleTime:long: an IdleStateEvent whose state is IdleState#ALL_IDLE will be triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.
unit:TimeUnit: the TimeUnit of readerIdleTime, writeIdleTime, and allIdleTime

Method Detail

channelActive back to summary

channelActive	back to summary
public void channelActive(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelActive. Implements io.netty.channel.ChannelInboundHandler.channelActive. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelActive. Calls `ChannelHandlerContext#fireChannelActive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelActive(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelActive.

Implements io.netty.channel.ChannelInboundHandler.channelActive.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelActive.

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

Annotations

@Override

channelIdle	back to summary
protected void channelIdle(ChannelHandlerContext ctx, IdleStateEvent evt) throws Exception Is called when an `IdleStateEvent` should be fired. This implementation calls `ChannelHandlerContext#fireUserEventTriggered(Object)`.

channelInactive back to summary

channelInactive	back to summary
public void channelInactive(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Implements io.netty.channel.ChannelInboundHandler.channelInactive. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelInactive. Calls `ChannelHandlerContext#fireChannelInactive()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelInactive(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelInactive.

Implements io.netty.channel.ChannelInboundHandler.channelInactive.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelInactive.

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

Annotations

@Override

channelRead back to summary

channelRead	back to summary
public void channelRead(ChannelHandlerContext ctx, Object msg) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Implements io.netty.channel.ChannelInboundHandler.channelRead. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRead. Calls `ChannelHandlerContext#fireChannelRead(Object)` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

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

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRead.

Implements io.netty.channel.ChannelInboundHandler.channelRead.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRead.

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

Annotations

@Override

channelReadComplete back to summary

channelReadComplete	back to summary
public void channelReadComplete(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Implements io.netty.channel.ChannelInboundHandler.channelReadComplete. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete. Calls `ChannelHandlerContext#fireChannelReadComplete()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelReadComplete(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete.

Implements io.netty.channel.ChannelInboundHandler.channelReadComplete.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelReadComplete.

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

Annotations

@Override

channelRegistered back to summary

channelRegistered	back to summary
public void channelRegistered(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRegistered. Implements io.netty.channel.ChannelInboundHandler.channelRegistered. Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRegistered. Calls `ChannelHandlerContext#fireChannelRegistered()` to forward to the next `ChannelInboundHandler` in the `ChannelPipeline`. Sub-classes may override this method to change behavior. Annotations @Override

public void channelRegistered(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelInboundHandlerAdapter.channelRegistered.

Implements io.netty.channel.ChannelInboundHandler.channelRegistered.

Doc from io.netty.channel.ChannelInboundHandlerAdapter.channelRegistered.

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

Annotations

@Override

destroy	back to summary
private void destroy()

getAllIdleTimeInMillis	back to summary
public long getAllIdleTimeInMillis() Return the allIdleTime that was given when instance this class in milliseconds.

getReaderIdleTimeInMillis	back to summary
public long getReaderIdleTimeInMillis() Return the readerIdleTime that was given when instance this class in milliseconds.

getWriterIdleTimeInMillis	back to summary
public long getWriterIdleTimeInMillis() Return the writerIdleTime that was given when instance this class in milliseconds.

handlerAdded back to summary

handlerAdded	back to summary
public void handlerAdded(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelHandlerAdapter.handlerAdded. Implements io.netty.channel.ChannelHandler.handlerAdded. Doc from io.netty.channel.ChannelHandler.handlerAdded. Gets called after the `ChannelHandler` was added to the actual context and it's ready to handle events. Annotations @Override

public void handlerAdded(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelHandlerAdapter.handlerAdded.

Implements io.netty.channel.ChannelHandler.handlerAdded.

Doc from io.netty.channel.ChannelHandler.handlerAdded.

Gets called after the ChannelHandler was added to the actual context and it's ready to handle events.

Annotations

@Override

handlerRemoved back to summary

handlerRemoved	back to summary
public void handlerRemoved(ChannelHandlerContext ctx) throws Exception Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved. Implements io.netty.channel.ChannelHandler.handlerRemoved. Doc from io.netty.channel.ChannelHandler.handlerRemoved. Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore. Annotations @Override

public void handlerRemoved(ChannelHandlerContext ctx) throws Exception

Overrides io.netty.channel.ChannelHandlerAdapter.handlerRemoved.

Implements io.netty.channel.ChannelHandler.handlerRemoved.

Doc from io.netty.channel.ChannelHandler.handlerRemoved.

Gets called after the ChannelHandler was removed from the actual context and it doesn't handle events anymore.

Annotations

@Override

hasOutputChanged	back to summary
private boolean hasOutputChanged(ChannelHandlerContext ctx, boolean first) Returns `true` if and only if the `IdleStateHandler` was constructed with `observeOutput` enabled and there has been an observed change in the `ChannelOutboundBuffer` between two consecutive calls of this method. https://github.com/netty/netty/issues/6150

initialize	back to summary
private void initialize(ChannelHandlerContext ctx)

initOutputChanged	back to summary
private void initOutputChanged(ChannelHandlerContext ctx) See Also `hasOutputChanged(ChannelHandlerContext, boolean)`

newIdleStateEvent	back to summary
protected IdleStateEvent newIdleStateEvent(IdleState state, boolean first) Returns a `IdleStateEvent`.

resetReadTimeout	back to summary
public void resetReadTimeout() Reset the read timeout. As this handler is not thread-safe, this method must be called on the event loop.

resetWriteTimeout	back to summary
public void resetWriteTimeout() Reset the write timeout. As this handler is not thread-safe, this method must be called on the event loop.

schedule	back to summary
pack-priv Future<?> schedule(ChannelHandlerContext ctx, Runnable task, long delay, TimeUnit unit) This method is visible for testing!

ticksInNanos	back to summary
pack-priv long ticksInNanos() This method is visible for testing!

write back to summary

public void write(ChannelHandlerContext ctx, Object msg, ChannelPromise promise) throws Exception

Overrides io.netty.channel.ChannelDuplexHandler.write.

Implements io.netty.channel.ChannelOutboundHandler.write.

Doc from io.netty.channel.ChannelDuplexHandler.write.

Calls ChannelHandlerContext#write(Object, ChannelPromise) to forward to the next ChannelOutboundHandler in the ChannelPipeline. Sub-classes may override this method to change behavior.

Parameters

ctx:ChannelHandlerContext

Doc from io.netty.channel.ChannelOutboundHandler.write.

the ChannelHandlerContext for which the write operation is made

msg:Object

Doc from io.netty.channel.ChannelOutboundHandler.write.

the message to write

promise:ChannelPromise

Doc from io.netty.channel.ChannelOutboundHandler.write.

the ChannelPromise to notify once the operation completes

Annotations

@Override

Exceptions

Exception:

Doc from io.netty.channel.ChannelOutboundHandler.write.

thrown if an error occurs

public Class IdleStateHandler

Supported idle states

Nested and Inner Type Summary

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private abstract Class IdleStateHandler.AbstractIdleTask

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail

private final Class IdleStateHandler.AllIdleTimeoutTask

Constructor Summary

Method Summary

Constructor Detail

Method Detail

private final Class IdleStateHandler.ReaderIdleTimeoutTask

Constructor Summary

Method Summary

Constructor Detail

Method Detail

private final Class IdleStateHandler.WriterIdleTimeoutTask

Constructor Summary

Method Summary

Constructor Detail

Method Detail

Modifier and Type	Method and Description
public void	run() Implements java.lang.Runnable.run. Runs this operation.
protected abstract void	run(ChannelHandlerContext ctx)