netty/netty — pull request #878 by trustin (2012-12-31 09:34:40+00:00)
Title: Read on demand

This pull request introduces a new operation called `read()` that replaces the existing inbound traffic control method. `EventLoop` now performs socket reads only when the `read()` operation has been issued. Once the requested `read()` operation is actually performed, `EventLoop` triggers an `inboundBufferSuspended` event that tells the handlers that the requested `read()` operation has been performed and the inbound traffic has been suspended again. A handler can decide to continue reading or not.

Unlike other outbound operations, `read()` does not evaluated by a pipeline. It directly goes to `EventLoop`. If there's a good reason to intercept the `read()` operation, I'll change this.

This pull request consequently removes the `readable` property in `ChannelHandlerContext`, which means how the traffic control works changed significantly.

From the performance standpoint, I see no regression.

Another interesting fact is that non-terminal handlers do not really need to call `read()` at all. Only the last inbound handler will have to call it, and that's just enough.

### How to port your last handler

1. In your handler's `channelActive()` method, call `ctx.read()`.
2. Override or implement `inboundBufferSuspended()` method and call `ctx.read()` there.

Again, do NOT need to call `ctx.read()` in non-terminal inbound handlers.

### Status

All testsuite test cases pass, but I did not port all examples. `HttpSnoopServer` does work. I'll continue porting all examples. It's pretty trivial, so you might want to do it yourself if you are eager to test.