// NewTimer creates a new Timer that will send
// the current time on its channel after at least duration d.
func NewTimer(d Duration) *Timer {
	c := make(chan Time, 1)
	t := &Timer{
		C: c,
		r: runtimeTimer{
			when: when(d),
			f:    sendTime,
			arg:  c,
		},
	}
	startTimer(&t.r)
	return t
}
// The Timer type represents a single event.
// When the Timer expires, the current time will be sent on C,
// unless the Timer was created by AfterFunc.
// A Timer must be created with NewTimer or AfterFunc.
type Timer struct {
	C <-chan Time
	r runtimeTimer
}

func NewTicker(d Duration) *Ticker {
	if d <= 0 {
		panic(errors.New("non-positive interval for NewTicker"))
	}
	// Give the channel a 1-element time buffer.
	// If the client falls behind while reading, we drop ticks
	// on the floor until the client catches up.
	c := make(chan Time, 1)
	t := &Ticker{
		C: c,
		r: runtimeTimer{
			when:   when(d),
			period: int64(d),
			f:      sendTime,
			arg:    c,
		},
	}
	startTimer(&t.r)
	return t
}
type Ticker struct {
	C <-chan Time // The channel on which the ticks are delivered.
	r runtimeTimer
}

// Interface to timers implemented in package runtime.
// Must be in sync with ../runtime/time.go:/^type timer
type runtimeTimer struct {
	pp       uintptr
	when     int64 //觸發(fā)時間
	period   int64 //執(zhí)行周期性任務的時間間隔
	f        func(any, uintptr) // 執(zhí)行的回調函數，NOTE: must not be closure
	arg      any //執(zhí)行任務的參數
	seq      uintptr //回調函數的參數，該參數僅在 netpoll 的應用場景下使用
	nextwhen int64 //如果是周期性任務，下次執(zhí)行任務時間
	status   uint32 //狀態(tài)
}
// sendTime does a non-blocking send of the current time on c.
func sendTime(c any, seq uintptr) {
	select {
	case c.(chan Time) <- Now():
	default:
	}
}

// runtime/runtime2.go
type p struct {
    .....
    // The when field of the first entry on the timer heap.
	// This is updated using atomic functions.
	// This is 0 if the timer heap is empty.
    // 堆頂元素什么時候執(zhí)行
	timer0When uint64
    // The earliest known nextwhen field of a timer with
	// timerModifiedEarlier status. Because the timer may have been
	// modified again, there need not be any timer with this value.
	// This is updated using atomic functions.
	// This is 0 if there are no timerModifiedEarlier timers.
    // 如果有timer修改為更早執(zhí)行時間了，將會將執(zhí)行時間更新到更早時間
	timerModifiedEarliest uint64
    // Lock for timers. We normally access the timers while running
	// on this P, but the scheduler can also do it from a different P.
    // 操作timer的互斥鎖
	timersLock mutex
    // Actions to take at some time. This is used to implement the
	// standard library's time package.
	// Must hold timersLock to access.
    //該p 上的所有timer,必須加鎖去操作這個字段，因為不同的p 操作這個字段會有競爭關系
	timers []*timer
	// Number of timers in P's heap.
	// Modified using atomic instructions.
    //p 堆上所有的timer數
	numTimers uint32
    // Number of timerDeleted timers in P's heap.
	// Modified using atomic instructions.
    //被標記為刪除的timer,要么是我們調用stop,要么是timer 自己觸發(fā)后過期導致的刪除
	deletedTimers uint32
}
// runtime/time.go
type timer struct {
	// If this timer is on a heap, which P's heap it is on.
	// puintptr rather than *p to match uintptr in the versions
	// of this struct defined in other packages.
	pp puintptr
	// Timer wakes up at when, and then at when+period, ... (period > 0 only)
	// each time calling f(arg, now) in the timer goroutine, so f must be
	// a well-behaved function and not block.
	//
	// when must be positive on an active timer.
	when   int64
	period int64
	f      func(any, uintptr)
	arg    any
	seq    uintptr
	// What to set the when field to in timerModifiedXX status.
	nextwhen int64
	// The status field holds one of the values below.
	status uint32
}
// startTimer adds t to the timer heap.
//go:linkname startTimer time.startTimer
func startTimer(t *timer) {
	if raceenabled {
		racerelease(unsafe.Pointer(t))
	}
	addtimer(t)
}
// stopTimer stops a timer.
// It reports whether t was stopped before being run.
//go:linkname stopTimer time.stopTimer
func stopTimer(t *timer) bool {
	return deltimer(t)
}
// addtimer adds a timer to the current P.
// This should only be called with a newly created timer.
// That avoids the risk of changing the when field of a timer in some P's heap,
// which could cause the heap to become unsorted.
func addtimer(t *timer) {
	// when must be positive. A negative value will cause runtimer to
	// overflow during its delta calculation and never expire other runtime
	// timers. Zero will cause checkTimers to fail to notice the timer.
	if t.when <= 0 {
		throw("timer when must be positive")
	}
	if t.period < 0 {
		throw("timer period must be non-negative")
	}
	if t.status != timerNoStatus {
		throw("addtimer called with initialized timer")
	}
	t.status = timerWaiting
	when := t.when
	// Disable preemption while using pp to avoid changing another P's heap.
    // 如果M在此之后被別的P搶占了，那么后續(xù)操作的就是別的P上的timers，這是不允許的
	mp := acquirem()
	pp := getg().m.p.ptr()
	lock(&pp.timersLock)
	cleantimers(pp) // 清理掉已經過期的timer，以提高添加和刪除timer的效率。
	doaddtimer(pp, t) // 執(zhí)行添加操作
	unlock(&pp.timersLock)
    // 調用 wakeNetPoller 方法，喚醒網絡輪詢器，檢查計時器被喚醒的時間（when）是
    // 否在當前輪詢預期運行的時間（pollerPollUntil）內，若是喚醒。
    // 有的定時器是伴隨著網絡輪訓器的，比如設置的 i/o timeout
    // This can have a spurious wakeup but should never miss a wakeup
    // 寧愿出現錯誤的喚醒，也不能漏掉一個喚醒
	wakeNetPoller(when)
	releasem(mp)
}
// 將0位置的timer與下面的子節(jié)點比較，如果比子節(jié)點大則下移。子節(jié)點i*4 + 1，i*4 + 2，i*4 + 3，i*4 + 4
siftdownTimer(pp.timers, 0) 
// 將i位置的timer與上面的父節(jié)點比較，如果比父節(jié)點小則上移。父節(jié)點是(i - 1) / 4
siftupTimer(pp.timers, i) 

//go:nosplit
func acquirem() *m {
	_g_ := getg()
	_g_.m.locks++
	return _g_.m
}
//go:nosplit
func releasem(mp *m) {
	_g_ := getg()
	mp.locks--
	if mp.locks == 0 && _g_.preempt {
		// restore the preemption request in case we've cleared it in newstack
		_g_.stackguard0 = stackPreempt
	}
}

//C:\Go\src\runtime\preempt.go +287
func canPreemptM(mp *m) bool {
   return mp.locks == 0 && mp.mallocing == 0 && mp.preemptoff == "" && mp.p.ptr().status == _Prunning
}

// runtime/proc.go
func checkTimers(pp *p, now int64) (rnow, pollUntil int64, ran bool)
// runtime/time.go
func runtimer(pp *p, now int64) int64
func runOneTimer(pp *p, t *timer, now int64)