Netty 5.0.0.Alpha5 · io.netty5.handler.traffic.GlobalChannelTrafficShapingHandler

This implementation of the AbstractTrafficShapingHandler is for global and per channel traffic shaping, that is to say a global limitation of the bandwidth, whatever the number of opened channels and a per channel limitation of the bandwidth.

This version shall not be in the same pipeline than other TrafficShapingHandler.

The general use should be as follow:

Create your unique GlobalChannelTrafficShapingHandler like:

GlobalChannelTrafficShapingHandler myHandler = new GlobalChannelTrafficShapingHandler(executor);

The executor could be the underlying IO worker pool
pipeline.addLast(myHandler);

Note that this handler has a Pipeline Coverage of "all" which means only one such handler must be created and shared among all channels as the counter must be shared among all channels.

Other arguments can be passed like write or read limitation (in bytes/s where 0 means no limitation) or the check interval (in millisecond) that represents the delay between two computations of the bandwidth and so the call back of the doAccounting method (0 means no accounting at all).
Note that as this is a fusion of both Global and Channel Traffic Shaping, limits are in 2 sets, respectively Global and Channel.

A value of 0 means no accounting for checkInterval. If you need traffic shaping but no such accounting, it is recommended to set a positive value, even if it is high since the precision of the Traffic Shaping depends on the period where the traffic is computed. The highest the interval, the less precise the traffic shaping will be. It is suggested as higher value something close to 5 or 10 minutes.

maxTimeToWait, by default set to 15s, allows to specify an upper bound of time shaping.
In your handler, you should consider to use the channel.isWritable() and channelWritabilityChanged(ctx) to handle writability, or through future.addListener(future -> ...) on the future returned by ctx.write().
You shall also consider to have object size in read or write operations relatively adapted to the bandwidth you required: for instance having 10 MB objects for 10KB/s will lead to burst effect, while having 100 KB objects for 1 MB/s should be smoothly handle by this TrafficShaping handler.
Some configuration methods will be taken as best effort, meaning that all already scheduled traffics will not be changed, but only applied to new traffics.
So the expected usage of those methods are to be used not too often, accordingly to the traffic shaping configuration.

Be sure to call release() once this handler is not needed anymore to release all internal resources. This will not shutdown the EventExecutor as it may be shared, so you need to do this by your own.

Nested and Inner Type Summary

Modifier and Type	Class and Description
pack-priv static class	GlobalChannelTrafficShapingHandler.PerChannel
private static class	GlobalChannelTrafficShapingHandler.ToSend

Field Summary

Modifier and Type	Field and Description
private volatile float	accelerationFactor
pack-priv final ConcurrentMap<Integer, GlobalChannelTrafficShapingHandler.PerChannel>	channelQueues All queues per channel
private final AtomicLong	cumulativeReadBytes Maximum cumulative read bytes for one channel among all (as long as channels stay the same)
private final AtomicLong	cumulativeWrittenBytes Maximum cumulative writing bytes for one channel among all (as long as channels stay the same)
private static final float	DEFAULT_ACCELERATION
private static final float	DEFAULT_DEVIATION
private static final float	DEFAULT_SLOWDOWN
private static final InternalLogger	logger Hides io.netty5.handler.traffic.AbstractTrafficShapingHandler.logger.
private static final float	MAX_DEVIATION
private volatile float	maxDeviation
pack-priv volatile long	maxGlobalWriteSize Max size in the list before proposing to stop writing new objects from next handlers for all channel (global)
private final AtomicLong	queuesSize Global queues size
private volatile long	readChannelLimit Limit in B/s to apply to read
private volatile boolean	readDeviationActive
private volatile float	slowDownFactor
private volatile long	writeChannelLimit Limit in B/s to apply to write
private volatile boolean	writeDeviationActive

Inherited from io.netty5.handler.traffic.AbstractTrafficShapingHandler:: CHANNEL_DEFAULT_USER_DEFINED_WRITABILITY_INDEX checkInterval DEFAULT_CHECK_INTERVAL DEFAULT_MAX_SIZE DEFAULT_MAX_TIME GLOBAL_DEFAULT_USER_DEFINED_WRITABILITY_INDEX GLOBALCHANNEL_DEFAULT_USER_DEFINED_WRITABILITY_INDEX maxTime maxWriteDelay maxWriteSize MINIMAL_WAIT READ_SUSPENDED REOPEN_TASK trafficCounter userDefinedWritabilityIndex

Constructor Summary

Access	Constructor and Description
public	GlobalChannelTrafficShapingHandler(EventExecutorGroup the `EventExecutorGroup` to use for the `TrafficCounter`. executor, long 0 or a limit in bytes/s writeGlobalLimit, long 0 or a limit in bytes/s readGlobalLimit, long 0 or a limit in bytes/s writeChannelLimit, long 0 or a limit in bytes/s readChannelLimit, long The delay between two computations of performances for channels or 0 if no stats are to be computed. checkInterval, long The maximum delay to wait in case of traffic excess. maxTime) Create a new instance.
public	GlobalChannelTrafficShapingHandler(EventExecutorGroup the `EventExecutorGroup` to use for the `TrafficCounter`. executor, long 0 or a limit in bytes/s writeGlobalLimit, long 0 or a limit in bytes/s readGlobalLimit, long 0 or a limit in bytes/s writeChannelLimit, long 0 or a limit in bytes/s readChannelLimit, long The delay between two computations of performances for channels or 0 if no stats are to be computed. checkInterval) Create a new instance.
public	GlobalChannelTrafficShapingHandler(EventExecutorGroup the `EventExecutorGroup` to use for the `TrafficCounter`. executor, long 0 or a limit in bytes/s writeGlobalLimit, long 0 or a limit in bytes/s readGlobalLimit, long 0 or a limit in bytes/s writeChannelLimit, long 0 or a limit in bytes/s readChannelLimit) Create a new instance.
public	GlobalChannelTrafficShapingHandler(EventExecutorGroup the `EventExecutorGroup` to use for the `TrafficCounter`. executor, long The delay between two computations of performances for channels or 0 if no stats are to be computed. checkInterval) Create a new instance.
public	GlobalChannelTrafficShapingHandler(EventExecutorGroup the `EventExecutorGroup` to use for the `TrafficCounter`. executor) Create a new instance.

Method Summary

Modifier and Type	Method and Description
public float	Returns: the current acceleration factor accelerationFactor()
public void	channelRead(final ChannelHandlerContext ctx, final Object msg) Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.channelRead. Overrides default io.netty5.channel.ChannelHandler.channelRead. Invoked when the current `Channel` has read a message from the peer.
public Collection<TrafficCounter>	Returns: the list of TrafficCounters that exists at the time of the call. channelTrafficCounters() To allow for instance doAccounting to use the TrafficCounter per channel.
protected long	checkWaitReadTime(final ChannelHandlerContext ctx, long the wait delay computed in ms wait, final long the relative now time in ms now) Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.checkWaitReadTime. Method overridden in GTSH to take into account specific timer for the channel.
private long	computeBalancedWait(float maxLocal, float maxGlobal, long wait)
private void	computeDeviationCumulativeBytes()
public void	configureChannel(long Channel write limit newWriteLimit, long Channel read limit newReadLimit)
pack-priv void	createGlobalTrafficCounter(EventExecutorGroup executor) Create the global TrafficCounter
protected void	doAccounting(TrafficCounter the TrafficCounter that computes its performance counter) Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.doAccounting. Called each time the accounting is computed from the TrafficCounters.
public long	Returns: the maxGlobalWriteSize getMaxGlobalWriteSize()
private GlobalChannelTrafficShapingHandler.PerChannel	getOrSetPerChannel(ChannelHandlerContext ctx)
public long	Returns: Channel read limit getReadChannelLimit()
public long	Returns: Channel write limit getWriteChannelLimit()
public void	handlerAdded(ChannelHandlerContext ctx) Overrides default io.netty5.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.netty5.handler.traffic.AbstractTrafficShapingHandler.handlerRemoved. Overrides default io.netty5.channel.ChannelHandler.handlerRemoved. Gets called after the `ChannelHandler` was removed from the actual context and it doesn't handle events anymore.
protected void	informReadOperation(final ChannelHandlerContext ctx, final long the relative now time in ms now) Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.informReadOperation. Method overridden in GTSH to take into account specific timer for the channel.
public boolean	isSharable() Overrides default io.netty5.channel.ChannelHandler.isSharable. Returns `true` if this handler is sharable and thus can be added to more than one `ChannelPipeline`.
public float	Returns: the current max deviation maxDeviation()
protected long	maximumCumulativeReadBytes()
protected long	maximumCumulativeWrittenBytes()
public long	Returns: the global size of the buffers for all queues. queuesSize()
public final void	release() Release all internal resources of this instance.
private void	sendAllValid(final ChannelHandlerContext ctx, final GlobalChannelTrafficShapingHandler.PerChannel perChannel, final long now)
public void	setMaxDeviation(float the maximum deviation to allow during computation of average, default deviation being 0.1, so +/-10% of the desired bandwidth. Maximum being 0.4. maxDeviation, float the factor set as +x% to the too fast client (minimal value being 0, meaning no slow down factor), default being 40% (0.4). slowDownFactor, float the factor set as -x% to the too slow client (maximal value being 0, meaning no acceleration factor), default being -10% (-0.1). accelerationFactor)
public void	setMaxGlobalWriteSize(long the maximum Global Write Size allowed in the buffer globally for all channels before write suspended is set. maxGlobalWriteSize) Note the change will be taken as best effort, meaning that all already scheduled traffics will not be changed, but only applied to new traffics.
public void	setReadChannelLimit(long Channel read limit readLimit)
public void	setWriteChannelLimit(long Channel write limit writeLimit)
public float	Returns: the current slow down factor slowDownFactor()
protected void	submitWrite(final ChannelHandlerContext ctx, final Object msg, final long size, final long writedelay, final long now, final Promise<Void> promise) Implements abstract io.netty5.handler.traffic.AbstractTrafficShapingHandler.submitWrite.
public String	toString() Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.toString. Returns a string representation of the object.
protected int	userDefinedWritabilityIndex() Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.userDefinedWritabilityIndex.
public Future<Void>	write(final ChannelHandlerContext the `ChannelHandlerContext` for which the write operation is made ctx, final Object the message to write msg) Overrides io.netty5.handler.traffic.AbstractTrafficShapingHandler.write. Overrides default io.netty5.channel.ChannelHandler.write. Called once a write operation is made.

Field Detail

accelerationFactor	back to summary
private volatile float accelerationFactor

channelQueues	back to summary
pack-priv final ConcurrentMap<Integer, GlobalChannelTrafficShapingHandler.PerChannel> channelQueues All queues per channel

cumulativeReadBytes	back to summary
private final AtomicLong cumulativeReadBytes Maximum cumulative read bytes for one channel among all (as long as channels stay the same)

cumulativeWrittenBytes	back to summary
private final AtomicLong cumulativeWrittenBytes Maximum cumulative writing bytes for one channel among all (as long as channels stay the same)

DEFAULT_ACCELERATION	back to summary
private static final float DEFAULT_ACCELERATION

DEFAULT_DEVIATION	back to summary
private static final float DEFAULT_DEVIATION

DEFAULT_SLOWDOWN	back to summary
private static final float DEFAULT_SLOWDOWN

logger	back to summary
private static final InternalLogger logger Hides io.netty5.handler.traffic.AbstractTrafficShapingHandler.logger.

MAX_DEVIATION	back to summary
private static final float MAX_DEVIATION

maxDeviation	back to summary
private volatile float maxDeviation

maxGlobalWriteSize	back to summary
pack-priv volatile long maxGlobalWriteSize Max size in the list before proposing to stop writing new objects from next handlers for all channel (global)

queuesSize	back to summary
private final AtomicLong queuesSize Global queues size

readChannelLimit	back to summary
private volatile long readChannelLimit Limit in B/s to apply to read

readDeviationActive	back to summary
private volatile boolean readDeviationActive

slowDownFactor	back to summary
private volatile float slowDownFactor

writeChannelLimit	back to summary
private volatile long writeChannelLimit Limit in B/s to apply to write

writeDeviationActive	back to summary
private volatile boolean writeDeviationActive