2008-08-08 02:37:18 +02:00
|
|
|
/*
|
2012-06-04 22:31:44 +02:00
|
|
|
* Copyright 2012 The Netty Project
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2011-12-09 06:18:34 +01:00
|
|
|
* 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:
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2012-06-04 22:31:44 +02:00
|
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
2008-08-08 03:27:24 +02:00
|
|
|
*
|
2009-08-28 09:15:49 +02:00
|
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
2011-12-09 06:18:34 +01:00
|
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
2009-08-28 09:15:49 +02:00
|
|
|
* License for the specific language governing permissions and limitations
|
|
|
|
* under the License.
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
2011-12-09 04:38:59 +01:00
|
|
|
package io.netty.channel;
|
2008-08-08 02:37:18 +02:00
|
|
|
|
2012-11-15 22:04:37 +01:00
|
|
|
import io.netty.buffer.ByteBufAllocator;
|
2011-12-09 04:38:59 +01:00
|
|
|
import io.netty.channel.socket.SocketChannelConfig;
|
2008-09-02 14:04:04 +02:00
|
|
|
|
2012-05-12 17:40:28 +02:00
|
|
|
import java.nio.ByteBuffer;
|
|
|
|
import java.nio.channels.WritableByteChannel;
|
2012-05-01 10:53:38 +02:00
|
|
|
import java.util.Map;
|
|
|
|
|
2008-08-08 02:37:18 +02:00
|
|
|
/**
|
2008-09-02 15:45:14 +02:00
|
|
|
* A set of configuration properties of a {@link Channel}.
|
2008-09-02 09:13:20 +02:00
|
|
|
* <p>
|
2008-09-03 03:30:17 +02:00
|
|
|
* Please down-cast to more specific configuration type such as
|
|
|
|
* {@link SocketChannelConfig} or use {@link #setOptions(Map)} to set the
|
2008-09-02 15:45:14 +02:00
|
|
|
* transport-specific properties:
|
|
|
|
* <pre>
|
2010-02-02 03:00:04 +01:00
|
|
|
* {@link Channel} ch = ...;
|
|
|
|
* {@link SocketChannelConfig} cfg = <strong>({@link SocketChannelConfig}) ch.getConfig();</strong>
|
2008-09-03 03:30:17 +02:00
|
|
|
* cfg.setTcpNoDelay(false);
|
2008-09-02 15:45:14 +02:00
|
|
|
* </pre>
|
2008-08-08 02:37:18 +02:00
|
|
|
*
|
2008-09-24 13:28:46 +02:00
|
|
|
* <h3>Option map</h3>
|
|
|
|
*
|
|
|
|
* An option map property is a dynamic write-only property which allows
|
|
|
|
* the configuration of a {@link Channel} without down-casting its associated
|
|
|
|
* {@link ChannelConfig}. To update an option map, please call {@link #setOptions(Map)}.
|
|
|
|
* <p>
|
2012-05-11 13:44:00 +02:00
|
|
|
* All {@link ChannelConfig} has the following options:
|
|
|
|
*
|
|
|
|
* <table border="1" cellspacing="0" cellpadding="6">
|
|
|
|
* <tr>
|
|
|
|
* <th>Name</th><th>Associated setter method</th>
|
|
|
|
* </tr><tr>
|
2013-01-20 08:10:15 +01:00
|
|
|
* <td>{@link io.netty.channel.ChannelOption#CONNECT_TIMEOUT_MILLIS}</td><td>{@link #setConnectTimeoutMillis(int)}</td>
|
|
|
|
* </tr><tr>
|
|
|
|
* <td>{@link io.netty.channel.ChannelOption#WRITE_SPIN_COUNT}</td><td>{@link #setWriteSpinCount(int)}</td>
|
|
|
|
* </tr><tr>
|
|
|
|
* <td>{@link io.netty.channel.ChannelOption#ALLOCATOR}</td><td>{@link #setAllocator(ByteBufAllocator)}</td>
|
|
|
|
* </tr><tr>
|
|
|
|
* <td>{@link io.netty.channel.ChannelOption#AUTO_READ}</td><td>{@link #setAutoRead(boolean)}</td>
|
2012-05-11 13:44:00 +02:00
|
|
|
* </tr>
|
|
|
|
* </table>
|
|
|
|
* <p>
|
|
|
|
* More options are available in the sub-types of {@link ChannelConfig}. For
|
2008-09-24 13:28:46 +02:00
|
|
|
* example, you can configure the parameters which are specific to a TCP/IP
|
2012-05-12 17:40:28 +02:00
|
|
|
* socket as explained in {@link SocketChannelConfig}.
|
2012-05-01 11:17:12 +02:00
|
|
|
*
|
2011-12-09 04:38:59 +01:00
|
|
|
* @apiviz.has io.netty.channel.ChannelPipelineFactory
|
|
|
|
* @apiviz.composedOf io.netty.channel.ReceiveBufferSizePredictor
|
2009-04-28 14:11:01 +02:00
|
|
|
*
|
|
|
|
* @apiviz.excludeSubtypes
|
2008-08-08 02:37:18 +02:00
|
|
|
*/
|
|
|
|
public interface ChannelConfig {
|
2008-09-02 09:13:20 +02:00
|
|
|
|
2012-08-28 01:14:05 +02:00
|
|
|
/**
|
|
|
|
* Return all set {@link ChannelOption}'s.
|
|
|
|
*/
|
2012-05-12 17:40:28 +02:00
|
|
|
Map<ChannelOption<?>, Object> getOptions();
|
|
|
|
|
2008-09-02 09:13:20 +02:00
|
|
|
/**
|
|
|
|
* Sets the configuration properties from the specified {@link Map}.
|
|
|
|
*/
|
2012-05-12 17:40:28 +02:00
|
|
|
boolean setOptions(Map<ChannelOption<?>, ?> options);
|
|
|
|
|
2012-08-28 01:14:05 +02:00
|
|
|
/**
|
|
|
|
* Return the value of the given {@link ChannelOption}
|
|
|
|
*/
|
2012-05-12 17:40:28 +02:00
|
|
|
<T> T getOption(ChannelOption<T> option);
|
2008-09-02 09:13:20 +02:00
|
|
|
|
2009-02-25 15:53:31 +01:00
|
|
|
/**
|
|
|
|
* Sets a configuration property with the specified name and value.
|
|
|
|
* To override this method properly, you must call the super class:
|
|
|
|
* <pre>
|
2012-12-22 15:53:01 +01:00
|
|
|
* public boolean setOption(ChannelOption<T> option, T value) {
|
|
|
|
* if (super.setOption(option, value)) {
|
2009-02-25 15:53:31 +01:00
|
|
|
* return true;
|
|
|
|
* }
|
|
|
|
*
|
2012-12-22 15:53:01 +01:00
|
|
|
* if (option.equals(additionalOption)) {
|
2009-02-25 15:53:31 +01:00
|
|
|
* ....
|
|
|
|
* return true;
|
|
|
|
* }
|
|
|
|
*
|
|
|
|
* return false;
|
|
|
|
* }
|
|
|
|
* </pre>
|
|
|
|
*
|
|
|
|
* @return {@code true} if and only if the property has been set
|
|
|
|
*/
|
2012-05-12 17:40:28 +02:00
|
|
|
<T> boolean setOption(ChannelOption<T> option, T value);
|
2012-05-11 13:44:00 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the connect timeout of the channel in milliseconds. If the
|
|
|
|
* {@link Channel} does not support connect operation, this property is not
|
|
|
|
* used at all, and therefore will be ignored.
|
|
|
|
*
|
|
|
|
* @return the connect timeout in milliseconds. {@code 0} if disabled.
|
|
|
|
*/
|
|
|
|
int getConnectTimeoutMillis();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the connect timeout of the channel in milliseconds. If the
|
|
|
|
* {@link Channel} does not support connect operation, this property is not
|
|
|
|
* used at all, and therefore will be ignored.
|
|
|
|
*
|
|
|
|
* @param connectTimeoutMillis the connect timeout in milliseconds.
|
|
|
|
* {@code 0} to disable.
|
|
|
|
*/
|
2012-12-14 16:59:23 +01:00
|
|
|
ChannelConfig setConnectTimeoutMillis(int connectTimeoutMillis);
|
2012-05-12 17:40:28 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns the maximum loop count for a write operation until
|
|
|
|
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
|
|
|
* It is similar to what a spin lock is used for in concurrency programming.
|
|
|
|
* It improves memory utilization and write throughput depending on
|
|
|
|
* the platform that JVM runs on. The default value is {@code 16}.
|
|
|
|
*/
|
|
|
|
int getWriteSpinCount();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets the maximum loop count for a write operation until
|
|
|
|
* {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
|
|
|
|
* It is similar to what a spin lock is used for in concurrency programming.
|
|
|
|
* It improves memory utilization and write throughput depending on
|
|
|
|
* the platform that JVM runs on. The default value is {@code 16}.
|
|
|
|
*
|
|
|
|
* @throws IllegalArgumentException
|
|
|
|
* if the specified value is {@code 0} or less than {@code 0}
|
|
|
|
*/
|
2012-12-14 16:59:23 +01:00
|
|
|
ChannelConfig setWriteSpinCount(int writeSpinCount);
|
2012-11-15 22:04:37 +01:00
|
|
|
|
2012-12-14 16:59:23 +01:00
|
|
|
/**
|
|
|
|
* Returns {@link ByteBufAllocator} which is used for the channel
|
|
|
|
* to allocate buffers.
|
|
|
|
*/
|
2012-11-15 22:04:37 +01:00
|
|
|
ByteBufAllocator getAllocator();
|
2012-12-14 16:59:23 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Set the {@link ByteBufAllocator} which is used for the channel
|
|
|
|
* to allocate buffers.
|
|
|
|
*/
|
|
|
|
ChannelConfig setAllocator(ByteBufAllocator allocator);
|
Read only when requested (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 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.
2012-12-30 13:53:59 +01:00
|
|
|
|
|
|
|
/**
|
|
|
|
* Returns {@code true} if and only if {@link ChannelHandlerContext#read()} will be invoked automatically so that
|
|
|
|
* a user application doesn't need to call it at all. The default value is {@code true}.
|
|
|
|
*/
|
|
|
|
boolean isAutoRead();
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Sets if {@link ChannelHandlerContext#read()} will be invoked automatically so that a user application doesn't
|
|
|
|
* need to call it at all. The default value is {@code true}.
|
|
|
|
*/
|
|
|
|
ChannelConfig setAutoRead(boolean autoRead);
|
2008-08-08 02:37:18 +02:00
|
|
|
}
|