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 use ChannelFuture at all to avoid GC cost. If there's a good reason to create a new future per read at the GC cost, I'll change this. This pull request consequently removes the readable property in ChannelHandlerContext, which means how the traffic control works changed significantly. This pull request also adds a new configuration property ChannelOption.AUTO_READ whose default value is true. If true, Netty will call ctx.read() for you. If you need a close control over when read() is called, you can set it to false. 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. Actually, you don't even need to call it at the last handler in most cases because of the ChannelOption.AUTO_READ mentioned above. There's no serious backward compatibility issue. If the compiler complains your handler does not implement the read() method, add the following: public void read(ChannelHandlerContext ctx) throws Exception { ctx.read(); } Note that this pull request certainly makes bounded inbound buffer support very easy, but itself does not add the bounded inbound buffer support.
177 lines
7.2 KiB
Java
177 lines
7.2 KiB
Java
/*
|
|
* 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.
|
|
*/
|
|
package io.netty.channel;
|
|
|
|
import java.net.SocketAddress;
|
|
|
|
/**
|
|
* Interface which is shared by others which need to execute outbound logic.
|
|
*/
|
|
public interface ChannelOutboundInvoker {
|
|
|
|
/**
|
|
* Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of an error.
|
|
*/
|
|
ChannelFuture bind(SocketAddress localAddress);
|
|
|
|
/**
|
|
* Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*/
|
|
ChannelFuture connect(SocketAddress remoteAddress);
|
|
|
|
/**
|
|
* Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of
|
|
* an error.
|
|
*/
|
|
ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
|
|
|
|
/**
|
|
* Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*/
|
|
ChannelFuture disconnect();
|
|
|
|
/**
|
|
* Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* After it is closed it is not possible to reuse it again.
|
|
*/
|
|
ChannelFuture close();
|
|
|
|
/**
|
|
* Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
|
|
* {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
*/
|
|
ChannelFuture deregister();
|
|
|
|
/**
|
|
* Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*/
|
|
ChannelFuture flush();
|
|
|
|
/**
|
|
* Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*
|
|
* If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
|
|
*/
|
|
ChannelFuture write(Object message);
|
|
|
|
/**
|
|
* Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*/
|
|
ChannelFuture sendFile(FileRegion region);
|
|
|
|
/**
|
|
* Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture bind(SocketAddress localAddress, ChannelFuture future);
|
|
|
|
/**
|
|
* Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture connect(SocketAddress remoteAddress, ChannelFuture future);
|
|
|
|
/**
|
|
* Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
|
|
|
|
/**
|
|
* Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture disconnect(ChannelFuture future);
|
|
|
|
/**
|
|
* Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
|
|
* either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* After it is closed it is not possible to reuse it again.
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture close(ChannelFuture future);
|
|
|
|
/**
|
|
* Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
|
|
* {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
|
|
* an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture deregister(ChannelFuture future);
|
|
|
|
/**
|
|
* Reads data from the {@link Channel} into the first inbound buffer, triggers an
|
|
* {@link ChannelStateHandler#inboundBufferUpdated(ChannelHandlerContext) inboundBufferUpdated} event if data was
|
|
* read, and triggers an
|
|
* {@link ChannelStateHandler#inboundBufferSuspended(ChannelHandlerContext) inboundBufferSuspended} event so the
|
|
* handler can decide to continue reading. If there's a pending read operation already, this method does nothing.
|
|
*/
|
|
void read();
|
|
|
|
/**
|
|
* Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture flush(ChannelFuture future);
|
|
|
|
/**
|
|
* Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*
|
|
* If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture write(Object message, ChannelFuture future);
|
|
|
|
/**
|
|
* Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
|
|
* once the operation completes, either because the operation was successful or because of an error.
|
|
*
|
|
* The given {@link ChannelFuture} will be notified and also returned.
|
|
*/
|
|
ChannelFuture sendFile(FileRegion region, ChannelFuture future);
|
|
}
|