4.1 - Channel

Created by : Mr Dk.

2021 / 02 / 19 16:20

Ningbo, Zhejiang, China

Channel

Channel 的接口定义。

Definition

/**
 * A nexus to a network socket or a component which is capable of I/O
 * operations such as read, write, connect, and bind.
 * <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>
 * <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
 * <li>the {@link ChannelPipeline} which handles all I/O events and requests
 *     associated with the channel.</li>
 * </ul>
 *
 * <h3>All I/O operations are asynchronous.</h3>
 * <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
 * a {@link ChannelFuture} instance which will notify you when the requested I/O
 * operation has succeeded, failed, or canceled.
 *
 * <h3>Channels are hierarchical</h3>
 * <p>
 * A {@link Channel} can have a {@linkplain #parent() parent} depending on
 * how it was created.  For instance, a {@link SocketChannel}, that was accepted
 * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
 * as its parent on {@link #parent()}.
 * <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="https://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
 *
 * <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}.
 *
 * <h3>Release resources</h3>
 * <p>
 * It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all
 * resources once you are done with the {@link Channel}. This ensures all resources are
 * released in a proper way, i.e. filehandles.
 */
public interface Channel extends AttributeMap, ChannelOutboundInvoker, Comparable<Channel> {

}

ID

Channel 具有全局唯一的 ID。

/**
 * Returns the globally unique identifier of this {@link Channel}.
 */
ChannelId id();

EventLoop

Channel 会被注册到一个 EventLoop 上，由该 EventLoop 处理 Channel 的所有事件。

/**
 * Return the {@link EventLoop} this {@link Channel} was registered to.
 */
EventLoop eventLoop();

Pipeline

服务 Channel 的 ChannelPipeline。

/**
 * Return the assigned {@link ChannelPipeline}.
 */
ChannelPipeline pipeline();

Buffer Allocator

返回用于分配缓冲区的 ByteBufAllocator。

/**
 * Return the assigned {@link ByteBufAllocator} which will be used to allocate {@link ByteBuf}s.
 */
ByteBufAllocator alloc();

Configuration

/**
 * Returns the configuration of this channel.
 */
ChannelConfig config();

Status

返回当前 Channel 的状态。Channel 的状态包含：

Unregistered - Channel 已被创建，但还未注册到 EventLoop
Registered - Channel 已被注册到 EventLoop
Inactive - Channel 还未连接到远程结点
Active - Channel 已经连接到远程结点，可以收发数据

/**
 * Returns {@code true} if the {@link Channel} is open and may get active later
 */
boolean isOpen();

/**
 * Returns {@code true} if the {@link Channel} is registered with an {@link EventLoop}.
 */
boolean isRegistered();

/**
 * Return {@code true} if the {@link Channel} is active and so connected.
 */
boolean isActive();

Address

/**
 * 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.
 *
 * @return the local address of this channel.
 *         {@code null} if this channel is not bound.
 */
SocketAddress localAddress();

/**
 * 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.
 *
 * @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},
 *         use {@link DatagramPacket#recipient()} to determine
 *         the origination of the received message as this method will
 *         return {@code null}.
 */
SocketAddress remoteAddress();