org.jboss.netty.handler.traffic.package-info Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of netty Show documentation
Show all versions of netty Show documentation
The Netty project is an effort to provide an asynchronous event-driven
network application framework and tools for rapid development of
maintainable high performance and high scalability protocol servers and
clients. In other words, Netty is a NIO client server framework which
enables quick and easy development of network applications such as protocol
servers and clients. It greatly simplifies and streamlines network
programming such as TCP and UDP socket server.
/*
* Copyright 2012 The Netty Project
*
* The Netty Project licenses this file to you under the Apache License,
* version 2.0 (the "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at:
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations
* under the License.
*/
/**
* Implementation of a Traffic Shaping Handler and Dynamic Statistics.
*
*
*
* The main goal of this package is to allow to shape the traffic (bandwidth limitation),
* but also to get statistics on how many bytes are read or written. Both functions can
* be active or inactive (traffic or statistics).
*
* Two classes implement this behavior:
*
* - {@link org.jboss.netty.handler.traffic.TrafficCounter}: this class implements the counters
* needed by the handlers. It can be accessed to get some extra information like the read or
* write bytes since last check, the read and write bandwidth from last check...
*
* - {@link org.jboss.netty.handler.traffic.AbstractTrafficShapingHandler}: this abstract class
* implements the kernel of the traffic shaping. It could be extended to fit your needs. Two
* classes are proposed as default implementations: see
* {@link org.jboss.netty.handler.traffic.ChannelTrafficShapingHandler} and
* {@link org.jboss.netty.handler.traffic.GlobalTrafficShapingHandler} respectively for
* Channel traffic shaping and Global traffic shaping.
*
* The insertion in the pipeline of one of those handlers can be wherever you want, but
* it must be placed before any {@link org.jboss.netty.handler.execution.MemoryAwareThreadPoolExecutor}
* in your pipeline.
* It is really recommended to have such a
* {@link org.jboss.netty.handler.execution.MemoryAwareThreadPoolExecutor}
* (either non ordered or
* {@link org.jboss.netty.handler.execution.OrderedMemoryAwareThreadPoolExecutor}
* ) in your pipeline
* when you want to use this feature with some real traffic shaping, since it will allow to relax the constraint on
* NioWorker to do other jobs if necessary.
* Instead, if you don't, you can have the following situation: if there are more clients
* connected and doing data transfer (either in read or write) than NioWorker, your global performance can be under
* your specifications or even sometimes it will block for a while which can turn to "timeout" operations.
* For instance, let says that you've got 2 NioWorkers, and 10 clients wants to send data to your server.
* If you set a bandwidth limitation of 100KB/s for each channel (client), you could have a final limitation of about
* 60KB/s for each channel since NioWorkers are stopping by this handler.
* When it is used as a read traffic shaper, the handler will set the channel as not readable, so as to relax the
* NioWorkers.
* An {@link org.jboss.netty.util.ObjectSizeEstimator} can be passed at construction to specify what
* is the size of the object to be read or write accordingly to the type of
* object. If not specified, it will used the {@link org.jboss.netty.util.DefaultObjectSizeEstimator}
* implementation.
*
*
* Standard use could be as follow:
*
*
* - To activate or deactivate the traffic shaping, change the value corresponding to your desire as
* [Global or per Channel] [Write or Read] Limitation in byte/s.
* A value of 0
* stands for no limitation, so the traffic shaping is deactivate (on what you specified).
* You can either change those values with the method configure in
* {@link org.jboss.netty.handler.traffic.AbstractTrafficShapingHandler}.
*
*
* - To activate or deactivate the statistics, you can adjust the delay to a low (suggested not less than 200ms
* for efficiency reasons) or a high value (let say 24H in millisecond is huge enough to not get the problem)
* or even using 0 which means no computation will be done.
* If you want to do anything with this statistics, just override the doAccounting method.
* This interval can be changed either from the method configure in
* {@link org.jboss.netty.handler.traffic.AbstractTrafficShapingHandler}
* or directly using the method configure of {@link org.jboss.netty.handler.traffic.TrafficCounter}.
*
*
*
* So in your application you will create your own TrafficShapingHandler and set the values to fit your needs.
* XXXXXTrafficShapingHandler myHandler = new XXXXXTrafficShapingHandler(timer);
* timer could be created using HashedWheelTimer and XXXXX could be either
* Global or Channel
* pipeline.addLast("XXXXX_TRAFFIC_SHAPING", myHandler);
* ...
* pipeline.addLast("MemoryExecutor",new ExecutionHandler(memoryAwareThreadPoolExecutor));
* Note that a new {@link org.jboss.netty.handler.traffic.ChannelTrafficShapingHandler} must be
* created for each new channel, but only one {@link org.jboss.netty.handler.traffic.GlobalTrafficShapingHandler}
* must be created for all channels.
*
* Note also that you can create different GlobalTrafficShapingHandler if you want to separate classes of
* channels (for instance either from business point of view or from bind address point of view).
*
* @apiviz.exclude ^java\.lang\.
*/
package org.jboss.netty.handler.traffic;