HashedWheelTimer源码解析

最新推荐文章于 2026-06-20 10:00:34 发布

原创最新推荐文章于 2026-06-20 10:00:34 发布 · 361 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#源码

HashedWheelTimer 专栏收录该内容

1 篇文章

订阅专栏

本文深入剖析 Netty 中 HashedWheelTimer 的实现原理，介绍其核心数据结构与工作流程，包括时间轮的设计、任务调度机制及定时任务的执行过程。

HashedWheelTimer源码分析

HashedWheelTimer使用的是绝对时钟和增加round属性的方式。

结构分析

如图，HashedWheelTimer代表时间轮，是一个环形队列，底层使用数组实现，每个槽存储一个HashedWheelBucket，这个bucket就是存储任务列表的容器，里面有一个的双向链表HashedWheelTimeout，每一个HashedWheelTimeout里面有一个timer(TimerTask)代表任务。
在这里插入图片描述

源码分析

基本属性

HashedWheelTimer

// 全局实例计数器
private static final AtomicInteger INSTANCE_COUNTER = new AtomicInteger();
// 创建实例过多标识，超过64
private static final AtomicBoolean WARNED_TOO_MANY_INSTANCES = new AtomicBoolean();
// 默认实例过多数目 64
private static final int INSTANCE_COUNT_LIMIT = 64;
// 标识最小时间精度为1ms
private static final long MILLISECOND_NANOS = TimeUnit.MILLISECONDS.toNanos(1);
// netty的内存泄漏探测器 ----  记录ByteBuf的使用，监控占用资源的对象
private static final ResourceLeakDetector<HashedWheelTimer> leakDetector =  	ResourceLeakDetectorFactory.instance().newResourceLeakDetector(HashedWheelTimer.class, 1);
// 维护状态机的原子更新器
private static final AtomicIntegerFieldUpdater<HashedWheelTimer> WORKER_STATE_UPDATER =
        AtomicIntegerFieldUpdater.newUpdater(HashedWheelTimer.class, "workerState");
// netty的内存泄漏探测器 - 监控当前调度器对象
private final ResourceLeakTracker<HashedWheelTimer> leak;
// 实际调度线程
private final Worker worker = new Worker();
private final Thread workerThread;
// 状态机 初始 -> 启动 -> 停止
public static final int WORKER_STATE_INIT = 0;
public static final int WORKER_STATE_STARTED = 1;
public static final int WORKER_STATE_SHUTDOWN = 2;
@SuppressWarnings({ "unused", "FieldMayBeFinal" })
private volatile int workerState; // 0 - init, 1 - started, 2 - shut down
// 时间精度 
private final long tickDuration;
// 代表时间轮的数组
private final HashedWheelBucket[] wheel;
// 掩码  定位时间轮的格子  mask = wheel.length - 1，执行 ticks & mask
private final int mask;
// 启动标识锁
private final CountDownLatch startTimeInitialized = new CountDownLatch(1);
// 队列用于缓冲外部提交时间轮中的定时任务
private final Queue<HashedWheelTimeout> timeouts = PlatformDependent.newMpscQueue();
//  队列用于暂存取消的定时任务
private final Queue<HashedWheelTimeout> cancelledTimeouts = PlatformDependent.newMpscQueue();
// 统计待执行的Timeouts数量
private final AtomicLong pendingTimeouts = new AtomicLong(0);
private final long maxPendingTimeouts;
// 时间轮的启动时间，所有定时任务以改时间为起点进行计算
private volatile long startTime;

HashedWheelBucket

// 任务列表的 头、尾指针
private HashedWheelTimeout head;
private HashedWheelTimeout tail;

HashedWheelTimeoud

// 状态机 
private static final int ST_INIT = 0;
private static final int ST_CANCELLED = 1;
private static final int ST_EXPIRED = 2;
// 原子更新器
private static final AtomicIntegerFieldUpdater<HashedWheelTimeout> STATE_UPDATER =
        AtomicIntegerFieldUpdater.newUpdater(HashedWheelTimeout.class, "state");

// 所在时间轮
private final HashedWheelTimer timer;
// 任务
private final TimerTask task;
// 触发时间点
private final long deadline;

@SuppressWarnings({"unused", "FieldMayBeFinal", "RedundantFieldInitialization" })
private volatile int state = ST_INIT;

// 当前任务的剩余时钟周期数，就是之前说的round属性，经过计算后得出触发时间点发生的套圈
long remainingRounds;

// 前后节点指针
HashedWheelTimeout next;
HashedWheelTimeout prev;

// 所在槽的指针
HashedWheelBucket bucket;

构造函数

创建时间轮数组，长度为传入的长度最接近的2的幂次，方便通过掩码定位格子。
将时间刻度转换为纳秒
通过workFactory封装worker线程，延迟启动，直到第一个任务添加时才启动。

/**
**	threadFactory -> 封装worker的线程工厂
**	tickDuration  -> 时间精度(每个格子)
**	unit				  -> 时间精度单位
**  ticksPerWheel -> 时间轮的大小
**  leakDetection -> 监控内存泄漏
**  maxPendingTimeouts -> 未执行的最大任务数 -1代表不限
**/
public HashedWheelTimer(
        ThreadFactory threadFactory,
        long tickDuration, TimeUnit unit, int ticksPerWheel, boolean leakDetection,
        long maxPendingTimeouts) {

    ObjectUtil.checkNotNull(threadFactory, "threadFactory");
    ObjectUtil.checkNotNull(unit, "unit");
    ObjectUtil.checkPositive(tickDuration, "tickDuration");
    ObjectUtil.checkPositive(ticksPerWheel, "ticksPerWheel");

    // 初始化时间轮
    wheel = createWheel(ticksPerWheel);
    mask = wheel.length - 1;

    // 转换时间刻度为纳秒
    long duration = unit.toNanos(tickDuration);

    // 防止栈溢出
    if (duration >= Long.MAX_VALUE / wheel.length) {
        throw new IllegalArgumentException(String.format(
                "tickDuration: %d (expected: 0 < tickDuration in nanos < %d",
                tickDuration, Long.MAX_VALUE / wheel.length));
    }

    // 最小时间刻度不能小于1ms
    if (duration < MILLISECOND_NANOS) {
        logger.warn("Configured tickDuration {} smaller then {}, using 1ms.",
                    tickDuration, MILLISECOND_NANOS);
        this.tickDuration = MILLISECOND_NANOS;
    } else {
        this.tickDuration = duration;
    }

    // 构建调度线程
    workerThread = threadFactory.newThread(worker);

  	// 初始化内存泄漏监控
    leak = leakDetection || !workerThread.isDaemon() ? leakDetector.track(this) : null;
		
    // 时间轮容纳的最大待执行任务数
    this.maxPendingTimeouts = maxPendingTimeouts;
		
    // 时间轮实例过大报告
    if (INSTANCE_COUNTER.incrementAndGet() > INSTANCE_COUNT_LIMIT &&
        WARNED_TOO_MANY_INSTANCES.compareAndSet(false, true)) {
        reportTooManyInstances();
    }
}

private static HashedWheelBucket[] createWheel(int ticksPerWheel) {
    if (ticksPerWheel <= 0) {
      throw new IllegalArgumentException(
        "ticksPerWheel must be greater than 0: " + ticksPerWheel);
    }
    if (ticksPerWheel > 1073741824) {
      throw new IllegalArgumentException(
        "ticksPerWheel may not be greater than 2^30: " + ticksPerWheel);
    }
		// 找出最接近的2的幂次数
    ticksPerWheel = normalizeTicksPerWheel(ticksPerWheel);
    HashedWheelBucket[] wheel = new HashedWheelBucket[ticksPerWheel];
    for (int i = 0; i < wheel.length; i ++) {
      wheel[i] = new HashedWheelBucket();
    }
    return wheel;
}

private static int normalizeTicksPerWheel(int ticksPerWheel) {
    int normalizedTicksPerWheel = 1;
    while (normalizedTicksPerWheel < ticksPerWheel) {
      normalizedTicksPerWheel <<= 1;
    }
    return normalizedTicksPerWheel;
}

添加任务并启动

如果时间轮没启动先启动时间轮，记录当前startTime。
通过该任务执行的延时时间计算deadline。
构建timeout节点，并放到队列中。

@Override
public Timeout newTimeout(TimerTask task, long delay, TimeUnit unit) {
    ObjectUtil.checkNotNull(task, "task");
    ObjectUtil.checkNotNull(unit, "unit");

    long pendingTimeoutsCount = pendingTimeouts.incrementAndGet();
		// 判断是否超过最大任务数
    if (maxPendingTimeouts > 0 && pendingTimeoutsCount > maxPendingTimeouts) {
        pendingTimeouts.decrementAndGet();
        throw new RejectedExecutionException("Number of pending timeouts ("
            + pendingTimeoutsCount + ") is greater than or equal to maximum allowed pending "
            + "timeouts (" + maxPendingTimeouts + ")");
    }
		
  	// 如果时间轮还没启动  先启动
    start();

    // 基于时间轮启动时间计算deadline
    long deadline = System.nanoTime() + unit.toNanos(delay) - startTime;

    // Guard against overflow.
    if (delay > 0 && deadline < 0) {
        deadline = Long.MAX_VALUE;
    }
  	// 构建timeout节点，放到队列中
    HashedWheelTimeout timeout = new HashedWheelTimeout(this, task, deadline);
    timeouts.add(timeout);
    return timeout;
}

/**
** 启动worker线程 cas更新状态 初始 -> 启动
**/ 
public void start() {
    switch (WORKER_STATE_UPDATER.get(this)) {
      case WORKER_STATE_INIT:
        if (WORKER_STATE_UPDATER.compareAndSet(this, WORKER_STATE_INIT, WORKER_STATE_STARTED)) {
          workerThread.start();
        }
        break;
      case WORKER_STATE_STARTED:
        break;
      case WORKER_STATE_SHUTDOWN:
        throw new IllegalStateException("cannot be started once stopped");
      default:
        throw new Error("Invalid WorkerState");
    }

    // 等待worker启动
    while (startTime == 0) {
      try {
        startTimeInitialized.await();
      } catch (InterruptedException ignore) {
        // Ignore - it will be ready very soon.
      }
    }
}

时间轮执行

启动的时候先记录startTime，释放startTimeInitialized锁，通知等待的线程继续执行
进入dowhile循环，调用waitForNextTick等待指针跳动，返回当前已经执行的时间。
定位此次tick跳动到的槽。
移除已经撤销的任务。
将任务缓冲队列中任务加到时间轮中。
遍历当前槽位中的任务并执行

@Override
public void run() {
    // 初始化启动时间
    startTime = System.nanoTime();
    if (startTime == 0) {
        // We use 0 as an indicator for the uninitialized value here, so make sure it's not 0 when initialized.
        startTime = 1;
    }

    // 通知启动时间轮的线程继续执行
    startTimeInitialized.countDown();

  	// while-true 时间轮转动
    do {
      	// 等待时间轮转动
        final long deadline = waitForNextTick();
        if (deadline > 0) {
            // 定位槽
            int idx = (int) (tick & mask);
            // 处理撤销的任务
            processCancelledTasks();
            HashedWheelBucket bucket = wheel[idx];
            // 将队列中的任务转移到时间轮中
            transferTimeoutsToBuckets();
          	// 触发到期任务的expire方法
            bucket.expireTimeouts(deadline);
            tick++;
        }
    } while (WORKER_STATE_UPDATER.get(HashedWheelTimer.this) == WORKER_STATE_STARTED);

    // 遍历所有的桶以及队列，取出未过期或未撤销的任务
    for (HashedWheelBucket bucket: wheel) {
        bucket.clearTimeouts(unprocessedTimeouts);
    }
    for (;;) {
        HashedWheelTimeout timeout = timeouts.poll();
        if (timeout == null) {
            break;
        }
        if (!timeout.isCancelled()) {
            unprocessedTimeouts.add(timeout);
        }
    }
  	//处理被撤销的任务
    processCancelledTasks();
}

Tick 时钟跳动

计算下一个tick的deadline。
计算sleep的毫秒数，不足1ms的补足1ms。
sleepTimeMs <= 0代表到达了一下个时间刻度，有2中情况，一种是前一个格子调度耗时比较长，另一种是正常sleep后。立即结束。

private long waitForNextTick() {
  	// 时间刻度 * Tick下一次跳动的次数 = deadline
    long deadline = tickDuration * (tick + 1);

    for (;;) {
      	// 计算需要sleep的时间, 之所以加999999后再除10000000, 是为了不足1ms的补足1ms
        final long currentTime = System.nanoTime() - startTime;
        long sleepTimeMs = (deadline - currentTime + 999999) / 1000000;
				
      	// 代表走到了下一个时间轮的格子
        if (sleepTimeMs <= 0) {
          	// 时间轮运转的时间过长发生栈溢出？？？
            if (currentTime == Long.MIN_VALUE) {
                return -Long.MAX_VALUE;
            } else {
                return currentTime;
            }
        }

        // Check if we run on windows, as if thats the case we will need
        // to round the sleepTime as workaround for a bug that only affect
        // the JVM if it runs on windows.
        //
        // See https://github.com/netty/netty/issues/356
        if (PlatformDependent.isWindows()) {
            sleepTimeMs = sleepTimeMs / 10 * 10;
            if (sleepTimeMs == 0) {
                sleepTimeMs = 1;
            }
        }

        try {
            Thread.sleep(sleepTimeMs);
        } catch (InterruptedException ignored) {
            if (WORKER_STATE_UPDATER.get(HashedWheelTimer.this) == WORKER_STATE_SHUTDOWN) {
                return Long.MIN_VALUE;
            }
        }
    }
}

处理被取消的任务

这个方法的流程就是从已取消的任务队列中取数据，然后remove掉，就是双链表的删除。

private void processCancelledTasks() {
    for (;;) {
        HashedWheelTimeout timeout = cancelledTimeouts.poll();
        if (timeout == null) {
            // all processed
            break;
        }
        try {
            timeout.remove();
        } catch (Throwable t) {
            if (logger.isWarnEnabled()) {
                logger.warn("An exception was thrown while process a cancellation task", t);
            }
        }
    }
}

void remove() {
    HashedWheelBucket bucket = this.bucket;
    if (bucket != null) {
      bucket.remove(this);
    } else {
      timer.pendingTimeouts.decrementAndGet();
    }
}

将任务添加到时间轮中

该方法是从timeouts（就是前面newTimeout是放进去的那个queue）的queue中取出任务，放到格子里（HashedWheelBucket是一个链表），为了防止这个操作销毁太多时间，导致更多的任务时间不准，因此一次最多操作10w个。
为了防止出现任务延迟太久，因此在计算模之前，还先取max in (calculated, tick），从而让那些本应该在过去执行的任务，在这期先快速执行掉。

private void transferTimeoutsToBuckets() {
    // 每次处理10w个任务，防止阻塞。
    for (int i = 0; i < 100000; i++) {
        HashedWheelTimeout timeout = timeouts.poll();
        if (timeout == null) {
            // all processed
            break;
        }
        if (timeout.state() == HashedWheelTimeout.ST_CANCELLED) {
            // Was cancelled in the meantime.
            continue;
        }
				
      	// 计算时间轮要转几轮才能执行这个任务
        long calculated = timeout.deadline / tickDuration;
        timeout.remainingRounds = (calculated - tick) / wheel.length;

      	// 放到对应的槽中 已经过期的任务要快速执行
        final long ticks = Math.max(calculated, tick); // Ensure we don't schedule for past.
        int stopIndex = (int) (ticks & mask);

        HashedWheelBucket bucket = wheel[stopIndex];
        bucket.addTimeout(timeout);
    }
}

执行调度

就是一次遍历任务列表，如果remainingRounds（剩下的圈数）小于等于0，那么就把他移除并执行expire方法（即TimerTask的run方法）；如果任务被取消了，则直接移除；否则remainingRounds减一，等待下一圈。
这里有一点，如果run方法执行时间过长，很可能会阻塞后面任务的正常执行。

public void expireTimeouts(long deadline) {
    HashedWheelTimeout timeout = head;

    // process all timeouts
    while (timeout != null) {
        HashedWheelTimeout next = timeout.next;
        if (timeout.remainingRounds <= 0) {
            next = remove(timeout);
            if (timeout.deadline <= deadline) {
                timeout.expire();
            } else {
                // The timeout was placed into a wrong slot. This should never happen.
                throw new IllegalStateException(String.format(
                        "timeout.deadline (%d) > deadline (%d)", timeout.deadline, deadline));
            }
        } else if (timeout.isCancelled()) {
            next = remove(timeout);
        } else {
            timeout.remainingRounds --;
        }
        timeout = next;
    }
}

public void expire() {
    if (!compareAndSetState(ST_INIT, ST_EXPIRED)) {
      return;
    }

    try {
      task.run(this);
    } catch (Throwable t) {
      if (logger.isWarnEnabled()) {
        logger.warn("An exception was thrown by " + TimerTask.class.getSimpleName() + '.', t);
      }
    }
}