1 /*
2 * Copyright 2009 Red Hat, Inc.
3 *
4 * Red Hat licenses this file to you under the Apache License, version 2.0
5 * (the "License"); you may not use this file except in compliance with the
6 * License. You may obtain a copy of the License at:
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations
14 * under the License.
15 */
16 package org.jboss.netty.channel.socket.nio;
17
18 import java.nio.ByteBuffer;
19 import java.nio.channels.WritableByteChannel;
20
21 import org.jboss.netty.channel.AdaptiveReceiveBufferSizePredictor;
22 import org.jboss.netty.channel.AdaptiveReceiveBufferSizePredictorFactory;
23 import org.jboss.netty.channel.Channel;
24 import org.jboss.netty.channel.ChannelConfig;
25 import org.jboss.netty.channel.ReceiveBufferSizePredictor;
26 import org.jboss.netty.channel.ReceiveBufferSizePredictorFactory;
27 import org.jboss.netty.channel.socket.SocketChannel;
28 import org.jboss.netty.channel.socket.SocketChannelConfig;
29
30 /**
31 * A {@link SocketChannelConfig} for a NIO TCP/IP {@link SocketChannel}.
32 *
33 * <h3>Available options</h3>
34 *
35 * In addition to the options provided by {@link ChannelConfig} and
36 * {@link SocketChannelConfig}, {@link NioSocketChannelConfig} allows the
37 * following options in the option map:
38 *
39 * <table border="1" cellspacing="0" cellpadding="6">
40 * <tr>
41 * <th>Name</th><th>Associated setter method</th>
42 * </tr><tr>
43 * <td>{@code "writeBufferHighWaterMark"}</td><td>{@link #setWriteBufferHighWaterMark(int)}</td>
44 * </tr><tr>
45 * <td>{@code "writeBufferLowWaterMark"}</td><td>{@link #setWriteBufferLowWaterMark(int)}</td>
46 * </tr><tr>
47 * <td>{@code "writeSpinCount"}</td><td>{@link #setWriteSpinCount(int)}</td>
48 * </tr><tr>
49 * <td>{@code "receiveBufferSizePredictor"}</td><td>{@link #setReceiveBufferSizePredictor(ReceiveBufferSizePredictor)}</td>
50 * </tr><tr>
51 * <td>{@code "receiveBufferSizePredictorFactory"}</td><td>{@link #setReceiveBufferSizePredictorFactory(ReceiveBufferSizePredictorFactory)}</td>
52 * </tr>
53 * </table>
54 *
55 * @author <a href="http://www.jboss.org/netty/">The Netty Project</a>
56 * @author <a href="http://gleamynode.net/">Trustin Lee</a>
57 *
58 * @version $Rev: 2080 $, $Date: 2010-01-26 18:04:19 +0900 (Tue, 26 Jan 2010) $
59 */
60 public interface NioSocketChannelConfig extends SocketChannelConfig {
61
62 /**
63 * Returns the high water mark of the write buffer. If the number of bytes
64 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
65 * will start to return {@code false}.
66 */
67 int getWriteBufferHighWaterMark();
68
69 /**
70 * Sets the high water mark of the write buffer. If the number of bytes
71 * queued in the write buffer exceeds this value, {@link Channel#isWritable()}
72 * will start to return {@code false}.
73 */
74 void setWriteBufferHighWaterMark(int writeBufferHighWaterMark);
75
76 /**
77 * Returns the low water mark of the write buffer. Once the number of bytes
78 * queued in the write buffer exceeded the
79 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
80 * dropped down below this value, {@link Channel#isWritable()} will return
81 * {@code true} again.
82 */
83 int getWriteBufferLowWaterMark();
84
85 /**
86 * Sets the low water mark of the write buffer. Once the number of bytes
87 * queued in the write buffer exceeded the
88 * {@linkplain #setWriteBufferHighWaterMark(int) high water mark} and then
89 * dropped down below this value, {@link Channel#isWritable()} will return
90 * {@code true} again.
91 */
92 void setWriteBufferLowWaterMark(int writeBufferLowWaterMark);
93
94 /**
95 * Returns the maximum loop count for a write operation until
96 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
97 * It is similar to what a spin lock is used for in concurrency programming.
98 * It improves memory utilization and write throughput depending on
99 * the platform that JVM runs on. The default value is {@code 16}.
100 */
101 int getWriteSpinCount();
102
103 /**
104 * Sets the maximum loop count for a write operation until
105 * {@link WritableByteChannel#write(ByteBuffer)} returns a non-zero value.
106 * It is similar to what a spin lock is used for in concurrency programming.
107 * It improves memory utilization and write throughput depending on
108 * the platform that JVM runs on. The default value is {@code 16}.
109 *
110 * @throws IllegalArgumentException
111 * if the specified value is {@code 0} or less than {@code 0}
112 */
113 void setWriteSpinCount(int writeSpinCount);
114
115 /**
116 * Returns the {@link ReceiveBufferSizePredictor} which predicts the
117 * number of readable bytes in the socket receive buffer. The default
118 * predictor is <tt>{@link AdaptiveReceiveBufferSizePredictor}(64, 1024, 65536)</tt>.
119 */
120 ReceiveBufferSizePredictor getReceiveBufferSizePredictor();
121
122 /**
123 * Sets the {@link ReceiveBufferSizePredictor} which predicts the
124 * number of readable bytes in the socket receive buffer. The default
125 * predictor is <tt>{@link AdaptiveReceiveBufferSizePredictor}(64, 1024, 65536)</tt>.
126 */
127 void setReceiveBufferSizePredictor(ReceiveBufferSizePredictor predictor);
128
129 /**
130 * Returns the {@link ReceiveBufferSizePredictorFactory} which creates a new
131 * {@link ReceiveBufferSizePredictor} when a new channel is created and
132 * no {@link ReceiveBufferSizePredictor} was set. If no predictor was set
133 * for the channel, {@link #setReceiveBufferSizePredictor(ReceiveBufferSizePredictor)}
134 * will be called with the new predictor. The default factory is
135 * <tt>{@link AdaptiveReceiveBufferSizePredictorFactory}(64, 1024, 65536)</tt>.
136 */
137 ReceiveBufferSizePredictorFactory getReceiveBufferSizePredictorFactory();
138
139 /**
140 * Sets the {@link ReceiveBufferSizePredictor} which creates a new
141 * {@link ReceiveBufferSizePredictor} when a new channel is created and
142 * no {@link ReceiveBufferSizePredictor} was set. If no predictor was set
143 * for the channel, {@link #setReceiveBufferSizePredictor(ReceiveBufferSizePredictor)}
144 * will be called with the new predictor. The default factory is
145 * <tt>{@link AdaptiveReceiveBufferSizePredictorFactory}(64, 1024, 65536)</tt>.
146 */
147 void setReceiveBufferSizePredictorFactory(ReceiveBufferSizePredictorFactory predictorFactory);
148 }