16 // A timer is a potentially repeating trigger for calling t.f(t.arg, t.seq).
20 // A timer is expected to be used by only one client goroutine at a time,
21 // but there will be concurrent access by the P managing that timer.
22 // Timer accesses are protected by the lock t.mu, with a snapshot of
24 // decisions about a timer without acquiring the lock.
25 type timer struct {  struct
31 	isChan bool         // timer has a channel; immutable; can be read without lock  argument
34 	// channel timer and stopping or resetting the timer.
46 	// a timer that is reset concurrently with unlockAndRun.
47 	// If the reset timer runs immediately, we can wind up with
48 	// concurrent calls to unlockAndRun for the same timer.
52 	// We use a uint8 to keep the timer struct small.
54 	// runs of a timer, where a concurrent run can only occur if
55 	// we start a run, unlock the timer, the timer is reset to a new
58 	// Since completing a run is fast, even 2 concurrent timer runs are
62 	blocked uint32 // number of goroutines blocked on timer's channel  argument
64 	// Timer wakes up at when, and then at when+period, ... (period > 0 only)
65 	// each time calling f(arg, seq, delay) in the timer goroutine, so f must be
75 	// Package time does not know about seq, but if this is a channel timer (t.isChan == true),
77 	// sends that correspond to an earlier (stale) timer configuration,
83 	// when the timer should have gone off and now. Normally that amount is
98 	// sendLock protects sends on the timer's channel.
103 // init initializes a newly allocated timer t.
104 // Any code that allocates a timer must call t.init before using it.
107 func (t *timer) init(f func(arg any, seq uintptr, delay int64), arg any) {  argument
130 	// raceCtx is the race context used while executing timer functions.
146 	timer *timer  member
158 	// This matters if we lock ts, delete the only timer from the heap,
167 // Timer state field.
169 	// timerHeaped is set when the timer is stored in some P's heap.
175 	// the timer appears can be locked and rearranged.
179 	// timerZombie is set when the timer has been stopped
183 	// be set, meaning that the timer was modified and then stopped.
184 	// A timer sending to a channel may be placed in timerZombie
185 	// to take it out of the heap even though the timer is not stopped,
190 // timerDebug enables printing a textual debug trace of all timer operations to stderr.
193 func (t *timer) trace(op string) {  argument
199 func (t *timer) trace1(op string) {  argument
221 // lock locks the timer, allowing reading or writing any of the timer fields.
222 func (t *timer) lock() {  argument
227 // unlock updates t.astate and unlocks the timer.
228 func (t *timer) unlock() {  argument
237 // t must be a timer with a channel.
238 func (t *timer) hchan() *hchan {  argument
251 // The timer set t.ts must be non-nil and locked, t must be t.ts.heap[0], and updateHeap
255 func (t *timer) updateHeap() (updated bool) {  argument
259 	if ts == nil || t != ts.heap[0].timer {
264 		// Take timer out of heap.
283 // maxWhen is the maximum value for timer's when field.
287 // timer heaps are valid.
304 	t := gp.timer
306 		t = new(timer)
308 		gp.timer = t
319 // We can't call timer.reset in timeSleep itself because if this is a short
321 // timer function, goroutineReady, before the goroutine has been parked.
323 	gp.timer.reset(gp.sleepWhen, 0)
327 // A timeTimer is a runtime-allocated time.Timer or time.Ticker
333 	timer  anonMember
336 // newTimer allocates and returns a new time.Timer or time.Ticker (same layout)
342 	t.timer.init(nil, nil)
345 		racerelease(unsafe.Pointer(&t.timer))
350 		c.timer = &t.timer
352 			throw("invalid timer channel: no capacity")
360 // stopTimer stops a timer.
368 // resetTimer resets an inactive timer, adding it to the timer heap.
370 // Reports whether the timer was modified before it was run.
375 		racerelease(unsafe.Pointer(&t.timer))
392 func (ts *timers) addHeap(t *timer) {
401 		throw("ts set in timer")
406 	if t == ts.heap[0].timer {
412 // The caller is responsible for locking the timer and for checking that we
413 // are running timers in async mode. If the timer needs to be run,
415 // The timer is always locked on return.
416 func (t *timer) maybeRunAsync() {  argument
419 		// If timer should have triggered already (but nothing looked at it yet),
425 		// timer ourselves now is fine.)
435 // stop stops the timer t. It may be on some other P, so we can't
438 // Reports whether the timer was stopped before it was run.
439 func (t *timer) stop() bool {  argument
462 		// See timer.unlockAndRun.
468 		// that we should return true: the timer was
485 // deleteMin removes timer 0 from ts.
489 	t := ts.heap[0].timer
510 // modify modifies an existing timer.
511 // This is called by the netpoll code or time.Ticker.Reset or time.Timer.Reset.
512 // Reports whether the timer was modified before it was run.
514 func (t *timer) modify(when, period int64, f func(arg any, seq uintptr, delay int64), arg any, seq …  argument
516 		throw("timer when must be positive")
519 		throw("timer period must be non-negative")
551 		// See comment in type timer above and in timers.adjust below.
565 		// See timer.unlockAndRun.
571 		// that we should return true: the timer was
597 func (t *timer) needsAdd() bool {  argument
623 // Concurrent calls to time.Timer.Reset or blockTimerChan
626 func (t *timer) maybeAdd() {  argument
632 	// has marked as idle with no timers, in which case the timer could
659 // reset resets the time when a timer should fire.
660 // If used for an inactive timer, the timer will become active.
661 // Reports whether the timer was active and was stopped.
662 func (t *timer) reset(when, period int64) bool {  argument
666 // cleanHead cleans up the head of the timer queue. This speeds up
689 		// in heap[0] for the tail of the heap, we'll get a non-zombie timer,
692 		if t := ts.heap[n-1].timer; t.astate.Load()&timerZombie != 0 {
705 		t := ts.heap[0].timer
726 // and then clears the timer state from src,
738 			t := tw.timer
765 	// timer, don't do anything. This speeds up programs that adjust
793 	// concurrent timer modifications in other goroutines; those will lock
794 	// the specific timer, set the timerModified bit, and set t.when.
814 	// Step 3 processes all modified timer values, justifying minWhenModified = 0.
821 	// Originally Step 3 locked every timer, which made sure any timer update that was
825 	// timer update already in progress during Steps 1+2, t.modify sets timerModified
835 		t := tw.timer
902 // and the time when the next timer should run or 0 if there is no next timer,
904 // If the time when the next timer should run is not 0,
911 	// If it's not yet time for the first timer, or the first adjusted
912 	// timer, then there is nothing to do.
933 		// Next timer is not ready to run, and we don't need to clear deleted timers.
966 // run examines the first timer in ts. If it is ready based on now,
967 // it runs the timer and removes or updates it.
968 // Returns 0 if it ran a timer, -1 if there are no more timers, or the time
969 // when the first timer should run.
971 // If a timer is run, this will temporarily unlock ts.
982 	t := tw.timer
1013 // unlockAndRun unlocks and runs the timer t (which must be locked).
1014 // If t is in a timer set (t.ts != nil), the caller must also have locked the timer set,
1015 // and this call will temporarily unlock the timer set while running the timer function.
1019 func (t *timer) unlockAndRun(now int64) {  argument
1076 			throw("too many concurrent timer firings")
1098 		// For a timer channel, we want to make sure that no stale sends
1103 		// unlock above, and then a t.stop or t.modify changes the timer
1110 		// If not, the timer has been updated and we should skip the send.
1148 			// First timer has no parent.
1155 			print("bad timer heap at ", i, ": ", p, ": ", ts.heap[p].when, ", ", i, ": ", tw.when, "\n")
1156 			throw("bad timer heap")
1160 		println("timer heap len", len(ts.heap), "!= atomic len", n)
1161 		throw("bad timer heap len")
1190 // timeSleepUntil returns the time when the next timer should fire. Returns
1224 // siftUp puts the timer at position i in the right place
1244 	if heap[i].timer != tw.timer {
1249 // siftDown puts the timer at position i in the right place
1284 	if heap[i].timer != tw.timer {
1302 // badTimer is called if the timer data structures have been corrupted,
1307 	throw("timer data corruption")
1310 // Timer channels.
1312 // maybeRunChan checks whether the timer needs to run
1314 // The timer must not be locked.
1315 func (t *timer) maybeRunChan() {  argument
1317 		// If the timer is in the heap, the ordinary timer code
1326 		// Timer in the heap, or not running at all, or not triggered.
1338 // blockTimerChan makes sure that c is in a timer heap,
1341 	t := c.timer
1351 	// the timer may still be in the heap but marked as a zombie.
1352 	// Unmark it in this case, if the timer is still pending.
1375 // unblockTimerChan removes c from the timer heap when nothing is
1378 	t := c.timer
1386 		// Last goroutine that was blocked on this timer.