1 /* 2 * Copyright 2012 The Netty Project 3 * 4 * The Netty Project licenses this file to you under the Apache License, 5 * version 2.0 (the "License"); you may not use this file except in compliance 6 * with the License. You may obtain a copy of the License at: 7 * 8 * https://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 io.netty.channel; 17 18 import io.netty.buffer.ByteBuf; 19 import io.netty.buffer.ByteBufAllocator; 20 import io.netty.channel.socket.DatagramChannel; 21 import io.netty.channel.socket.DatagramPacket; 22 import io.netty.channel.socket.ServerSocketChannel; 23 import io.netty.channel.socket.SocketChannel; 24 import io.netty.util.AttributeMap; 25 26 import java.net.InetSocketAddress; 27 import java.net.SocketAddress; 28 29 30 /** 31 * A nexus to a network socket or a component which is capable of I/O 32 * operations such as read, write, connect, and bind. 33 * <p> 34 * A channel provides a user: 35 * <ul> 36 * <li>the current state of the channel (e.g. is it open? is it connected?),</li> 37 * <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li> 38 * <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li> 39 * <li>the {@link ChannelPipeline} which handles all I/O events and requests 40 * associated with the channel.</li> 41 * </ul> 42 * 43 * <h3>All I/O operations are asynchronous.</h3> 44 * <p> 45 * All I/O operations in Netty are asynchronous. It means any I/O calls will 46 * return immediately with no guarantee that the requested I/O operation has 47 * been completed at the end of the call. Instead, you will be returned with 48 * a {@link ChannelFuture} instance which will notify you when the requested I/O 49 * operation has succeeded, failed, or canceled. 50 * 51 * <h3>Channels are hierarchical</h3> 52 * <p> 53 * A {@link Channel} can have a {@linkplain #parent() parent} depending on 54 * how it was created. For instance, a {@link SocketChannel}, that was accepted 55 * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel} 56 * as its parent on {@link #parent()}. 57 * <p> 58 * The semantics of the hierarchical structure depends on the transport 59 * implementation where the {@link Channel} belongs to. For example, you could 60 * write a new {@link Channel} implementation that creates the sub-channels that 61 * share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and 62 * <a href="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do. 63 * 64 * <h3>Downcast to access transport-specific operations</h3> 65 * <p> 66 * Some transports exposes additional operations that is specific to the 67 * transport. Down-cast the {@link Channel} to sub-type to invoke such 68 * operations. For example, with the old I/O datagram transport, multicast 69 * join / leave operations are provided by {@link DatagramChannel}. 70 * 71 * <h3>Release resources</h3> 72 * <p> 73 * It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all 74 * resources once you are done with the {@link Channel}. This ensures all resources are 75 * released in a proper way, i.e. filehandles. 76 */ 77 public interface Channel extends AttributeMap, ChannelOutboundInvoker, Comparable<Channel> { 78 79 /** 80 * Returns the globally unique identifier of this {@link Channel}. 81 */ 82 ChannelId id(); 83 84 /** 85 * Return the {@link EventLoop} this {@link Channel} was registered to. 86 */ 87 EventLoop eventLoop(); 88 89 /** 90 * Returns the parent of this channel. 91 * 92 * @return the parent channel. 93 * {@code null} if this channel does not have a parent channel. 94 */ 95 Channel parent(); 96 97 /** 98 * Returns the configuration of this channel. 99 */ 100 ChannelConfig config(); 101 102 /** 103 * Returns {@code true} if the {@link Channel} is open and may get active later 104 */ 105 boolean isOpen(); 106 107 /** 108 * Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}. 109 */ 110 boolean isRegistered(); 111 112 /** 113 * Return {@code true} if the {@link Channel} is active and so connected. 114 */ 115 boolean isActive(); 116 117 /** 118 * Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}. 119 */ 120 ChannelMetadata metadata(); 121 122 /** 123 * Returns the local address where this channel is bound to. The returned 124 * {@link SocketAddress} is supposed to be down-cast into more concrete 125 * type such as {@link InetSocketAddress} to retrieve the detailed 126 * information. 127 * 128 * @return the local address of this channel. 129 * {@code null} if this channel is not bound. 130 */ 131 SocketAddress localAddress(); 132 133 /** 134 * Returns the remote address where this channel is connected to. The 135 * returned {@link SocketAddress} is supposed to be down-cast into more 136 * concrete type such as {@link InetSocketAddress} to retrieve the detailed 137 * information. 138 * 139 * @return the remote address of this channel. 140 * {@code null} if this channel is not connected. 141 * If this channel is not connected but it can receive messages 142 * from arbitrary remote addresses (e.g. {@link DatagramChannel}, 143 * use {@link DatagramPacket#recipient()} to determine 144 * the origination of the received message as this method will 145 * return {@code null}. 146 */ 147 SocketAddress remoteAddress(); 148 149 /** 150 * Returns the {@link ChannelFuture} which will be notified when this 151 * channel is closed. This method always returns the same future instance. 152 */ 153 ChannelFuture closeFuture(); 154 155 /** 156 * Returns {@code true} if and only if the I/O thread will perform the 157 * requested write operation immediately. Any write requests made when 158 * this method returns {@code false} are queued until the I/O thread is 159 * ready to process the queued write requests. 160 */ 161 boolean isWritable(); 162 163 /** 164 * Get how many bytes can be written until {@link #isWritable()} returns {@code false}. 165 * This quantity will always be non-negative. If {@link #isWritable()} is {@code false} then 0. 166 */ 167 long bytesBeforeUnwritable(); 168 169 /** 170 * Get how many bytes must be drained from underlying buffers until {@link #isWritable()} returns {@code true}. 171 * This quantity will always be non-negative. If {@link #isWritable()} is {@code true} then 0. 172 */ 173 long bytesBeforeWritable(); 174 175 /** 176 * Returns an <em>internal-use-only</em> object that provides unsafe operations. 177 */ 178 Unsafe unsafe(); 179 180 /** 181 * Return the assigned {@link ChannelPipeline}. 182 */ 183 ChannelPipeline pipeline(); 184 185 /** 186 * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s. 187 */ 188 ByteBufAllocator alloc(); 189 190 @Override 191 Channel read(); 192 193 @Override 194 Channel flush(); 195 196 /** 197 * <em>Unsafe</em> operations that should <em>never</em> be called from user-code. These methods 198 * are only provided to implement the actual transport, and must be invoked from an I/O thread except for the 199 * following methods: 200 * <ul> 201 * <li>{@link #localAddress()}</li> 202 * <li>{@link #remoteAddress()}</li> 203 * <li>{@link #closeForcibly()}</li> 204 * <li>{@link #register(EventLoop, ChannelPromise)}</li> 205 * <li>{@link #deregister(ChannelPromise)}</li> 206 * <li>{@link #voidPromise()}</li> 207 * </ul> 208 */ 209 interface Unsafe { 210 211 /** 212 * Return the assigned {@link RecvByteBufAllocator.Handle} which will be used to allocate {@link ByteBuf}'s when 213 * receiving data. 214 */ 215 RecvByteBufAllocator.Handle recvBufAllocHandle(); 216 217 /** 218 * Return the {@link SocketAddress} to which is bound local or 219 * {@code null} if none. 220 */ 221 SocketAddress localAddress(); 222 223 /** 224 * Return the {@link SocketAddress} to which is bound remote or 225 * {@code null} if none is bound yet. 226 */ 227 SocketAddress remoteAddress(); 228 229 /** 230 * Register the {@link Channel} of the {@link ChannelPromise} and notify 231 * the {@link ChannelFuture} once the registration was complete. 232 */ 233 void register(EventLoop eventLoop, ChannelPromise promise); 234 235 /** 236 * Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelPromise} and notify 237 * it once its done. 238 */ 239 void bind(SocketAddress localAddress, ChannelPromise promise); 240 241 /** 242 * Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}. 243 * If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just 244 * pass {@code null} to it. 245 * 246 * The {@link ChannelPromise} will get notified once the connect operation was complete. 247 */ 248 void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelPromise promise); 249 250 /** 251 * Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelPromise} once the 252 * operation was complete. 253 */ 254 void disconnect(ChannelPromise promise); 255 256 /** 257 * Close the {@link Channel} of the {@link ChannelPromise} and notify the {@link ChannelPromise} once the 258 * operation was complete. 259 */ 260 void close(ChannelPromise promise); 261 262 /** 263 * Closes the {@link Channel} immediately without firing any events. Probably only useful 264 * when registration attempt failed. 265 */ 266 void closeForcibly(); 267 268 /** 269 * Deregister the {@link Channel} of the {@link ChannelPromise} from {@link EventLoop} and notify the 270 * {@link ChannelPromise} once the operation was complete. 271 */ 272 void deregister(ChannelPromise promise); 273 274 /** 275 * Schedules a read operation that fills the inbound buffer of the first {@link ChannelInboundHandler} in the 276 * {@link ChannelPipeline}. If there's already a pending read operation, this method does nothing. 277 */ 278 void beginRead(); 279 280 /** 281 * Schedules a write operation. 282 */ 283 void write(Object msg, ChannelPromise promise); 284 285 /** 286 * Flush out all write operations scheduled via {@link #write(Object, ChannelPromise)}. 287 */ 288 void flush(); 289 290 /** 291 * Return a special ChannelPromise which can be reused and passed to the operations in {@link Unsafe}. 292 * It will never be notified of a success or error and so is only a placeholder for operations 293 * that take a {@link ChannelPromise} as argument but for which you not want to get notified. 294 */ 295 ChannelPromise voidPromise(); 296 297 /** 298 * Returns the {@link ChannelOutboundBuffer} of the {@link Channel} where the pending write requests are stored. 299 */ 300 ChannelOutboundBuffer outboundBuffer(); 301 } 302 }