@Override
public final ChannelPipeline addLast(String name, ChannelHandler handler) {
    return addLast(null, name, handler);
}

@Override
public final ChannelPipeline addLast(EventExecutorGroup group, String name, ChannelHandler handler) {
    final AbstractChannelHandlerContext newCtx;
    // 线程同步，因为channel可能被暴露给用户线程，所以要做并发控制
    synchronized (this) {
        // 检查handler是否能被多次添加到流水线中
        checkMultiplicity(handler);

        /*
         * 创建ChannelHandlerContext，封装handler。
         * 这里如果指定了name（不是null），那么直接检查名称是否重复了
         * 如果没有指定name，则先生成名称
         *
         * 名称检查是会遍历pipeline中的所有context
         */
        newCtx = newContext(group, filterName(name, handler), handler);

        // 本质上就是一个双向链表的插入操作
        addLast0(newCtx);

        // If the registered is false it means that the channel was not registered on an eventLoop yet.
        // In this case we add the context to the pipeline and add a task that will call
        // ChannelHandler.handlerAdded(...) once the channel is registered.
        /*
         * 如果通道还未注册过
         */
        if (!registered) {
            // 修改其状态
            newCtx.setAddPending();
            // 封装延迟任务并添加到延迟任务链表中
            callHandlerCallbackLater(newCtx, true);
            return this;
        }

        EventExecutor executor = newCtx.executor();
        /*
         * 如果当前线程是事件循环中的线程，那么提前退出同步块，缓解线程因锁产生的竞争。
         */
        if (!executor.inEventLoop()) {
            // 执行添加handler的回调
            callHandlerAddedInEventLoop(newCtx, executor);
            return this;
        }
    }

    // 回调用户方法和设置状态
    callHandlerAdded0(newCtx);
    return this;
}

public final ChannelPipeline addLast(ChannelHandler handler) {
    return addLast(null, handler);
}

@Override
public final ChannelPipeline addLast(ChannelHandler... handlers) {
    return addLast(null, handlers);
}

@Override
public final ChannelPipeline addLast(EventExecutorGroup executor, ChannelHandler... handlers) {
    ObjectUtil.checkNotNull(handlers, "handlers");

    // 依次添加handler
    for (ChannelHandler h: handlers) {
        if (h == null) {
            break;
        }
        addLast(executor, null, h);
    }

    return this;
}

private static void checkMultiplicity(ChannelHandler handler) {
    if (handler instanceof ChannelHandlerAdapter) {
        ChannelHandlerAdapter h = (ChannelHandlerAdapter) handler;
        // 如果通道处理器以及被添加过了（可能是添加到其他通道的流水线中）而且不是shareable的，则抛出异常。
        if (!h.isSharable() && h.added) {
            throw new ChannelPipelineException(
                    h.getClass().getName() +
                    " is not a @Sharable handler, so can't be added or removed multiple times.");
        }
        h.added = true;
    }
}

private String filterName(String name, ChannelHandler handler) {
    if (name == null) { // 如果名称为null
        // 则生成名称，内部已包含重复性检查
        return generateName(handler);
    }
    // 检查名称是否重复
    checkDuplicateName(name);
    return name;
}

private String generateName(ChannelHandler handler) {
    // 获取缓存
    Map<Class<?>, String> cache = nameCaches.get();
    Class<?> handlerType = handler.getClass();
    // 获取缓存中的处理器名称
    String name = cache.get(handlerType);
    // 缓存中没有记录
    if (name == null) {
        // 生成名称
        name = generateName0(handlerType);
        // 添加到缓存中
        cache.put(handlerType, name);
    }

    // It's not very likely for a user to put more than one handler of the same type, but make sure to avoid
    // any name conflicts.  Note that we don't cache the names generated here.
    if (context0(name) != null) { // 如果链表中存在同名的通道处理器
        // 去掉默认的最后一个字符，即序号标记0
        String baseName = name.substring(0, name.length() - 1); // Strip the trailing '0'.
        // 从1开始，直到找到重复的名称为止
        for (int i = 1;; i ++) {
            // 在名称末尾添加上序号
            String newName = baseName + i;
            if (context0(newName) == null) { // 没有重复的情况
                // 返回名称
                name = newName;
                break;
            }
        }
    }
    return name;
}

private static String generateName0(Class<?> handlerType) {
    // 简单类名加上特殊结尾标记
    return StringUtil.simpleClassName(handlerType) + "#0";
}

private void checkDuplicateName(String name) {
    // 如果名称重复，则直接抛出异常
    if (context0(name) != null) {
        throw new IllegalArgumentException("Duplicate handler name: " + name);
    }
}

private AbstractChannelHandlerContext context0(String name) {
    // 从头结点开始遍历
    AbstractChannelHandlerContext context = head.next;
    // 遍历通道处理器上下文对象
    while (context != tail) {
        // 如果链表中已经存在相同名称的节点了
        if (context.name().equals(name)) {
            // 返回相同名称的通道上下文对象
            return context;
        }
        // 推动往后遍历
        context = context.next;
    }
    return null;
}

private AbstractChannelHandlerContext newContext(EventExecutorGroup group, String name, ChannelHandler handler) {
    return new DefaultChannelHandlerContext(this, childExecutor(group), name, handler);
}

// 该方法在选择执行器组里面的执行器
private EventExecutor childExecutor(EventExecutorGroup group) {
    if (group == null) {
        return null;
    }
    // 判断是否是单个执行器的组
    Boolean pinEventExecutor = channel.config().getOption(ChannelOption.SINGLE_EVENTEXECUTOR_PER_GROUP);
    // 如果不是单个执行器的组
    if (pinEventExecutor != null && !pinEventExecutor) {
        // 选择执行器
        return group.next();
    }

    // 执行到这里就说明是单个执行器的组了

    // 获取缓存对象
    Map<EventExecutorGroup, EventExecutor> childExecutors = this.childExecutors;
    if (childExecutors == null) { // 如果缓存还没初始化过
        // Use size of 4 as most people only use one extra EventExecutor.
        // 初始化缓存对象
        childExecutors = this.childExecutors = new IdentityHashMap<EventExecutorGroup, EventExecutor>(4);
    }
    // Pin one of the child executors once and remember it so that the same child executor
    // is used to fire events for the same channel.
    // 从缓存中获取执行器
    EventExecutor childExecutor = childExecutors.get(group);
    if (childExecutor == null) { // 如果缓存中没有记录
        // 选择执行器
        childExecutor = group.next();
        // 将结果添加到缓存中
        childExecutors.put(group, childExecutor);
    }
    return childExecutor;
}

final class DefaultChannelHandlerContext extends AbstractChannelHandlerContext {

    private final ChannelHandler handler;

    DefaultChannelHandlerContext(
            DefaultChannelPipeline pipeline, EventExecutor executor, String name, ChannelHandler handler) {
        super(pipeline, executor, name, handler.getClass());
        this.handler = handler;
    }

    @Override
    public ChannelHandler handler() {
        return handler;
    }
}

private void callHandlerAdded0(final AbstractChannelHandlerContext ctx) {
    try {
        // 执行添加handler的回调
        ctx.callHandlerAdded();
    } catch (Throwable t) {

    }
}

final void callHandlerAdded() throws Exception {
    // We must call setAddComplete before calling handlerAdded. Otherwise if the handlerAdded method generates
    // any pipeline events ctx.handler() will miss them because the state will not allow it.
    // 修改状态为已添加完毕
    if (setAddComplete()) {
        // 修改成功则执行回调
        handler().handlerAdded(this);
    }
}

final boolean setAddComplete() {
    // 自旋更新状态
    for (;;) {
        int oldState = handlerState;
        // 如果处理器已被移除
        if (oldState == REMOVE_COMPLETE) {
            return false;
        }
        // Ensure we never update when the handlerState is REMOVE_COMPLETE already.
        // oldState is usually ADD_PENDING but can also be REMOVE_COMPLETE when an EventExecutor is used that is not
        // exposing ordering guarantees.
        // CAS设置状态为已添加完毕
        if (HANDLER_STATE_UPDATER.compareAndSet(this, oldState, ADD_COMPLETE)) {
            return true;
        }
    }
}

private void callHandlerAddedInEventLoop(final AbstractChannelHandlerContext newCtx, EventExecutor executor) {
    // 修改其状态为ADD_PENDING，表示正在添加中
    newCtx.setAddPending();
    executor.execute(new Runnable() {
        @Override
        public void run() {
            callHandlerAdded0(newCtx);
        }
    });
}

private void callHandlerCallbackLater(AbstractChannelHandlerContext ctx, boolean added) {
    assert !registered;

    // 创建任务对象
    PendingHandlerCallback task = added ? new PendingHandlerAddedTask(ctx) : new PendingHandlerRemovedTask(ctx);
    // 获取链表头
    PendingHandlerCallback pending = pendingHandlerCallbackHead;
    if (pending == null) { // 如果链表没被初始化
        // 则初始化链表
        pendingHandlerCallbackHead = task;
    } else {
        // Find the tail of the linked-list.
        // 尾插法：将任务对象添加到链表中
        while (pending.next != null) {
            pending = pending.next;
        }
        pending.next = task;
    }
}

/*
 * 当通道注册到选择器中时该方法会被调用
 */
final void invokeHandlerAddedIfNeeded() {
    assert channel.eventLoop().inEventLoop();
    // 只有在第一次注册通道的时候才会调用
    if (firstRegistration) {
        firstRegistration = false;
        // We are now registered to the EventLoop. It's time to call the callbacks for the ChannelHandlers,
        // that were added before the registration was done.
        // 调用延时任务链表中的任务
        callHandlerAddedForAllHandlers();
    }
}

private void callHandlerAddedForAllHandlers() {
    // 临时变量
    final PendingHandlerCallback pendingHandlerCallbackHead;
    synchronized (this) {
        assert !registered;

        // This Channel itself was registered.
        // 修改属性表示通道已经注册到该流水线中了。
        registered = true;

        pendingHandlerCallbackHead = this.pendingHandlerCallbackHead;
        // Null out so it can be GC'ed.
        // 重置链表头，当前是在同步块中，是线程安全的
        this.pendingHandlerCallbackHead = null;
    }

    // This must happen outside of the synchronized(...) block as otherwise handlerAdded(...) may be called while
    // holding the lock and so produce a deadlock if handlerAdded(...) will try to add another handler from outside
    // the EventLoop.
    // 执行任务链表中的任务
    PendingHandlerCallback task = pendingHandlerCallbackHead;
    while (task != null) {
        // 执行任务
        task.execute();
        task = task.next;
    }
}

private final class PendingHandlerAddedTask extends PendingHandlerCallback {

    PendingHandlerAddedTask(AbstractChannelHandlerContext ctx) {
        super(ctx);
    }

    @Override
    public void run() {
        // 执行通道处理器添加回调
        callHandlerAdded0(ctx);
    }

    @Override
    void execute() {
        EventExecutor executor = ctx.executor();
        if (executor.inEventLoop()) {
            // 执行通道处理器添加回调
            callHandlerAdded0(ctx);
        } else {
            try {
                // 会在事件循环中执行到上面的run方法
                executor.execute(this);
            } catch (RejectedExecutionException e) {
                if (logger.isWarnEnabled()) {
                    logger.warn(
                            "Can't invoke handlerAdded() as the EventExecutor {} rejected it, removing handler {}.",
                            executor, ctx.name(), e);
                }
                atomicRemoveFromHandlerList(ctx);
                ctx.setRemoved();
            }
        }
    }
}

@Override
public final ChannelPipeline fireChannelRegistered() {
    // 从head开始传播注册事件
    AbstractChannelHandlerContext.invokeChannelRegistered(head);
    return this;
}

// 调用注册回调
static void invokeChannelRegistered(final AbstractChannelHandlerContext next) {
    // 获取执行器
    EventExecutor executor = next.executor();
    if (executor.inEventLoop()) {
        // 调用通道注册回调注册
        next.invokeChannelRegistered();
    } else {
        // 提交任务
        executor.execute(new Runnable() {
            @Override
            public void run() {
                /*
                 * static的invoke方法都是调用的实例invoke方法。
                 */
                next.invokeChannelRegistered();
            }
        });
    }
}

// 调用通道处理器的注册回调方法
private void invokeChannelRegistered() {
    if (invokeHandler()) {
        try {
            // DON'T CHANGE
            // Duplex handlers implements both out/in interfaces causing a scalability issue
            // see https://bugs.openjdk.org/browse/JDK-8180450
            // 获取通道处理器
            final ChannelHandler handler = handler();
            // 获取流水线中的头节点
            final DefaultChannelPipeline.HeadContext headContext = pipeline.head;
            /*
             * 这里分三种情况有什么意义，都是调用的相同的方法，参数也相同。
             */
            if (handler == headContext) {
                headContext.channelRegistered(this);
            } else if (handler instanceof ChannelDuplexHandler) {
                ((ChannelDuplexHandler) handler).channelRegistered(this);
            } else {
                ((ChannelInboundHandler) handler).channelRegistered(this);
            }
        } catch (Throwable t) {
            invokeExceptionCaught(t);
        }
    } else {
        fireChannelRegistered();
    }
}

@Override
public ChannelHandlerContext fireChannelRegistered() {
    /*
     * 重写的父类fire方法内部都是：
     * * 查找下一个InBound类型的context；
     * * 调用的对应的static方法。
     * （其他fire方法类似）
     */
    invokeChannelRegistered(findContextInbound(MASK_CHANNEL_REGISTERED));
    return this;
}

private AbstractChannelHandlerContext findContextInbound(int mask) {
    AbstractChannelHandlerContext ctx = this;
    EventExecutor currentExecutor = executor();
    // 遍历链表
    do {
        // 向前遍历
        ctx = ctx.next;
    } while (skipContext(ctx, currentExecutor, mask, MASK_ONLY_INBOUND));
    return ctx;
}

private AbstractChannelHandlerContext findContextOutbound(int mask) {
    AbstractChannelHandlerContext ctx = this;
    EventExecutor currentExecutor = executor();
    // 遍历链表
    do {
        // 向前遍历
        ctx = ctx.prev;
    } while (skipContext(ctx, currentExecutor, mask, MASK_ONLY_OUTBOUND));
    return ctx;
}

private static boolean skipContext(
        AbstractChannelHandlerContext ctx, EventExecutor currentExecutor, int mask, int onlyMask) {
    // Ensure we correctly handle MASK_EXCEPTION_CAUGHT which is not included in the MASK_EXCEPTION_CAUGHT
    // 判断是否至少有一个比特的掩码能匹配上
    return (ctx.executionMask & (onlyMask | mask)) == 0 ||
            // We can only skip if the EventExecutor is the same as otherwise we need to ensure we offload
            // everything to preserve ordering.
            //
            // See https://github.com/netty/netty/issues/10067
            (ctx.executor() == currentExecutor && (ctx.executionMask & mask) == 0);
}

static int mask(Class<? extends ChannelHandler> clazz) {
    // Try to obtain the mask from the cache first. If this fails calculate it and put it in the cache for fast
    // lookup in the future.
    Map<Class<? extends ChannelHandler>, Integer> cache = MASKS.get();
    // 从缓存中获取
    Integer mask = cache.get(clazz);
    // 缓存中
    if (mask == null) {
        // 判断执行类型
        mask = mask0(clazz);
        // 将结果加入缓存中
        cache.put(clazz, mask);
    }
    return mask;
}