netty5/transport/src/main/java/io/netty/channel/Channel.java

274 lines
10 KiB
Java
Raw Normal View History

/*
2012-06-04 22:31:44 +02:00
* 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:
*
2012-06-04 22:31:44 +02:00
* http://www.apache.org/licenses/LICENSE-2.0
*
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
* 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.
*/
2011-12-09 04:38:59 +01:00
package io.netty.channel;
import io.netty.buffer.ByteBuf;
import io.netty.buffer.MessageBuf;
2011-12-09 04:38:59 +01:00
import io.netty.channel.socket.DatagramChannel;
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
import io.netty.channel.socket.DatagramPacket;
2011-12-09 04:38:59 +01:00
import io.netty.channel.socket.ServerSocketChannel;
import io.netty.channel.socket.SocketChannel;
import io.netty.util.AttributeMap;
import java.net.InetSocketAddress;
import java.net.SocketAddress;
/**
2008-09-02 09:22:16 +02:00
* A nexus to a network socket or a component which is capable of I/O
* operations such as read, write, connect, and bind.
2008-09-02 09:13:20 +02:00
* <p>
* A channel provides a user:
* <ul>
* <li>the current state of the channel (e.g. is it open? is it connected?),</li>
* <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
2008-09-02 09:22:16 +02:00
* <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
2012-12-21 07:13:31 +01:00
* <li>the {@link ChannelPipeline} which handles all I/O events and requests
* associated with the channel.</li>
2008-09-02 09:13:20 +02:00
* </ul>
*
* <h3>All I/O operations are asynchronous.</h3>
2009-07-23 10:26:54 +02:00
* <p>
* All I/O operations in Netty are asynchronous. It means any I/O calls will
* return immediately with no guarantee that the requested I/O operation has
* been completed at the end of the call. Instead, you will be returned with
2009-07-23 10:26:54 +02:00
* a {@link ChannelFuture} instance which will notify you when the requested I/O
* operation has succeeded, failed, or canceled.
*
2009-07-23 10:26:54 +02:00
* <h3>Channels are hierarchical</h3>
* <p>
2012-12-21 07:13:31 +01:00
* A {@link Channel} can have a {@linkplain #parent() parent} depending on
2009-07-23 10:26:54 +02:00
* how it was created. For instance, a {@link SocketChannel}, that was accepted
* by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
2012-12-21 07:13:31 +01:00
* as its parent on {@link #parent()}.
2009-07-23 10:26:54 +02:00
* <p>
* The semantics of the hierarchical structure depends on the transport
* implementation where the {@link Channel} belongs to. For example, you could
* write a new {@link Channel} implementation that creates the sub-channels that
* share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
* <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
*
2010-04-16 07:07:37 +02:00
* <h3>Downcast to access transport-specific operations</h3>
* <p>
* Some transports exposes additional operations that is specific to the
* transport. Down-cast the {@link Channel} to sub-type to invoke such
* operations. For example, with the old I/O datagram transport, multicast
* join / leave operations are provided by {@link DatagramChannel}.
*
* @apiviz.landmark
2011-12-09 04:38:59 +01:00
* @apiviz.composedOf io.netty.channel.ChannelConfig
* @apiviz.composedOf io.netty.channel.ChannelPipeline
2009-04-28 14:11:01 +02:00
*
2011-12-09 05:59:41 +01:00
* @apiviz.exclude ^io\.netty\.channel\.([a-z]+\.)+[^\.]+Channel$
*/
ByteBufAllocator API w/ ByteBuf perf improvements This commit introduces a new API for ByteBuf allocation which fixes issue #643 along with refactoring of ByteBuf for simplicity and better performance. (see #62) A user can configure the ByteBufAllocator of a Channel via ChannelOption.ALLOCATOR or ChannelConfig.get/setAllocator(). The default allocator is currently UnpooledByteBufAllocator.HEAP_BY_DEFAULT. To allocate a buffer, do not use Unpooled anymore. do the following: ctx.alloc().buffer(...); // allocator chooses the buffer type. ctx.alloc().heapBuffer(...); ctx.alloc().directBuffer(...); To deallocate a buffer, use the unsafe free() operation: ((UnsafeByteBuf) buf).free(); The following is the list of the relevant changes: - Add ChannelInboundHandler.freeInboundBuffer() and ChannelOutboundHandler.freeOutboundBuffer() to let a user free the buffer he or she allocated. ChannelHandler adapter classes implement is already, so most users won't need to call free() by themselves. freeIn/OutboundBuffer() methods are invoked when a Channel is closed and deregistered. - All ByteBuf by contract must implement UnsafeByteBuf. To access an unsafe operation: ((UnsafeByteBuf) buf).internalNioBuffer() - Replace WrappedByteBuf and ByteBuf.Unsafe with UnsafeByteBuf to simplify overall class hierarchy and to avoid unnecesary instantiation of Unsafe instances on an unsafe operation. - Remove buffer reference counting which is confusing - Instantiate SwappedByteBuf lazily to avoid instantiation cost - Rename ChannelFutureFactory to ChannelPropertyAccess and move common methods between Channel and ChannelHandlerContext there. Also made it package-private to hide it from a user. - Remove unused unsafe operations such as newBuffer() - Add DetectionUtil.canFreeDirectBuffer() so that an allocator decides which buffer type to use safely
2012-11-15 22:04:37 +01:00
public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPropertyAccess, Comparable<Channel> {
2008-09-02 09:13:20 +02:00
/**
* Returns the unique integer ID of this channel.
2008-09-02 09:13:20 +02:00
*/
Integer id();
2008-09-02 09:13:20 +02:00
2012-08-28 01:14:05 +02:00
/**
* Return the {@link EventLoop} this {@link Channel} was registered too.
*/
EventLoop eventLoop();
2008-09-02 09:13:20 +02:00
/**
* Returns the parent of this channel.
*
* @return the parent channel.
2008-11-14 08:45:53 +01:00
* {@code null} if this channel does not have a parent channel.
2008-09-02 09:13:20 +02:00
*/
Channel parent();
2008-09-02 09:13:20 +02:00
/**
* Returns the configuration of this channel.
*/
ChannelConfig config();
2008-09-02 09:13:20 +02:00
2012-12-21 07:13:31 +01:00
/**
* Returns {@code true} if the {@link Channel} is open an may get active later
*/
boolean isOpen();
2012-12-21 07:13:31 +01:00
/**
* Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}.
*/
boolean isRegistered();
2012-12-21 07:13:31 +01:00
/**
* Return {@code true} if the {@link Channel} is active and so connected.
*/
boolean isActive();
2012-08-28 01:14:05 +02:00
/**
* Return the {@link ChannelMetadata} of the {@link Channel} which describe the nature of the {@link Channel}.
*/
ChannelMetadata metadata();
/**
* Return the last {@link ByteBuf} of the {@link ChannelPipeline} which belongs to this {@link Channel}.
*
* This method may throw an {@link NoSuchBufferException} if you try to access this buffer and the
* {@link ChannelPipeline} does not contain any {@link ByteBuf}.
*/
ByteBuf outboundByteBuffer();
/**
* Return the last {@link MessageBuf} of the {@link ChannelPipeline} which belongs to this {@link Channel}.
*
* This method may throw an {@link NoSuchBufferException} if you try to access this buffer and the
* {@link ChannelPipeline} does not contain any {@link MessageBuf}.
*/
<T> MessageBuf<T> outboundMessageBuffer();
2008-09-02 09:13:20 +02:00
/**
* Returns the local address where this channel is bound to. The returned
* {@link SocketAddress} is supposed to be down-cast into more concrete
* type such as {@link InetSocketAddress} to retrieve the detailed
* information.
2008-09-02 09:13:20 +02:00
*
* @return the local address of this channel.
* {@code null} if this channel is not bound.
*/
SocketAddress localAddress();
2008-09-02 09:13:20 +02:00
/**
* Returns the remote address where this channel is connected to. The
* returned {@link SocketAddress} is supposed to be down-cast into more
* concrete type such as {@link InetSocketAddress} to retrieve the detailed
* information.
2008-09-02 09:13:20 +02:00
*
* @return the remote address of this channel.
* {@code null} if this channel is not connected.
* If this channel is not connected but it can receive messages
* from arbitrary remote addresses (e.g. {@link DatagramChannel},
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
* use {@link DatagramPacket#remoteAddress()} to determine
* the origination of the received message as this method will
* return {@code null}.
2008-09-02 09:13:20 +02:00
*/
SocketAddress remoteAddress();
/**
* Returns the {@link ChannelFuture} which will be notified when this
* channel is closed. This method always returns the same future instance.
*/
ChannelFuture closeFuture();
2012-04-03 15:29:26 +02:00
2012-08-28 01:14:05 +02:00
/**
* <strong>Caution</strong> for transport implementations use only!
*/
Unsafe unsafe();
2012-08-28 01:14:05 +02:00
/**
* <strong>Unsafe</strong> operations that should <strong>never</strong> be called
* from user-code. These methods are only provided to implement the actual transport.
*/
interface Unsafe {
2012-08-28 01:14:05 +02:00
/**
* Return the {@link ChannelHandlerContext} which is directly connected to the outbound of the
* underlying transport.
*/
ChannelHandlerContext directOutboundContext();
2012-08-28 01:14:05 +02:00
/**
* Return a {@link VoidChannelFuture}. This method always return the same instance.
*/
ChannelFuture voidFuture();
2012-08-28 01:14:05 +02:00
/**
* Return the {@link SocketAddress} to which is bound local or
* {@code null} if none.
2012-08-28 01:14:05 +02:00
*/
SocketAddress localAddress();
2012-08-28 01:14:05 +02:00
/**
* Return the {@link SocketAddress} to which is bound remote or
* {@code null} if none is bound yet.
2012-08-28 01:14:05 +02:00
*/
SocketAddress remoteAddress();
2012-08-28 01:14:05 +02:00
/**
* Register the {@link Channel} of the {@link ChannelFuture} with the {@link EventLoop} and notify
* the {@link ChannelFuture} once the registration was complete.
*/
void register(EventLoop eventLoop, ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Bind the {@link SocketAddress} to the {@link Channel} of the {@link ChannelFuture} and notify
* it once its done.
*/
void bind(SocketAddress localAddress, ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Connect the {@link Channel} of the given {@link ChannelFuture} with the given remote {@link SocketAddress}.
* If a specific local {@link SocketAddress} should be used it need to be given as argument. Otherwise just
* pass {@code null} to it.
2012-08-28 01:14:05 +02:00
*
* The {@link ChannelFuture} will get notified once the connect operation was complete.
*/
void connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Disconnect the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the
* operation was complete.
*/
void disconnect(ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Close the {@link Channel} of the {@link ChannelFuture} and notify the {@link ChannelFuture} once the
* operation was complete.
*/
void close(ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Closes the {@link Channel} immediately without firing any events. Probably only useful
* when registration attempt failed.
*/
void closeForcibly();
2012-08-28 01:14:05 +02:00
/**
* Deregister the {@link Channel} of the {@link ChannelFuture} from {@link EventLoop} and notify the
* {@link ChannelFuture} once the operation was complete.
*/
void deregister(ChannelFuture future);
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
/**
* Schedules a read operation that fills the inbound buffer of the first {@link ChannelInboundHandler} in the
* {@link ChannelPipeline}. If there's already a pending read operation, this method does nothing.
*/
void beginRead();
2012-08-28 01:14:05 +02:00
/**
* Flush out all data that was buffered in the buffer of the {@link #directOutboundContext()} and was not
* flushed out yet. After that is done the {@link ChannelFuture} will get notified
*/
void flush(ChannelFuture future);
2012-08-28 01:14:05 +02:00
/**
* Flush out all data now.
*/
void flushNow();
2012-08-28 01:14:05 +02:00
2012-12-17 16:01:58 +01:00
/**
* Send a {@link FileRegion} to the remote peer and notify the {@link ChannelFuture} once it completes
* or an error was detected. Once the {@link FileRegion} was transfered or an error was thrown it will
2012-12-23 19:24:20 +01:00
* automaticly closed via {@link FileRegion#close()}.
2012-12-17 16:01:58 +01:00
*/
void sendFile(FileRegion region, ChannelFuture future);
}
}