src/time/sleep.go - go - Git at Google

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 package time

 import (
 	"internal/godebug"
 	"unsafe"
 )

 // Sleep pauses the current goroutine for at least the duration d.
 // A negative or zero duration causes Sleep to return immediately.
 func Sleep(d Duration)

 var asynctimerchan = godebug.New("asynctimerchan")

 // syncTimer returns c as an unsafe.Pointer, for passing to newTimer.
 // If the GODEBUG asynctimerchan has disabled the async timer chan
 // code, then syncTimer always returns nil, to disable the special
 // channel code paths in the runtime.
 func syncTimer(c chan Time) unsafe.Pointer {
 	// If asynctimerchan=1, we don't even tell the runtime
 	// about channel timers, so that we get the pre-Go 1.23 code paths.
 	if asynctimerchan.Value() == "1" {
 		return nil
 	}

 	// Otherwise pass to runtime.
 	// This handles asynctimerchan=0, which is the default Go 1.23 behavior,
 	// as well as asynctimerchan=2, which is like asynctimerchan=1
 	// but implemented entirely by the runtime.
 	// The only reason to use asynctimerchan=2 is for debugging
 	// a problem fixed by asynctimerchan=1: it enables the new
 	// GC-able timer channels (#61542) but not the sync channels (#37196).
 	//
 	// If we decide to roll back the sync channels, we will still have
 	// a fully tested async runtime implementation (asynctimerchan=2)
 	// and can make this function always return c.
 	//
 	// If we decide to keep the sync channels, we can delete all the
 	// handling of asynctimerchan in the runtime and keep just this
 	// function to handle asynctimerchan=1.
 	return *(*unsafe.Pointer)(unsafe.Pointer(&c))
 }

 // when is a helper function for setting the 'when' field of a runtimeTimer.
 // It returns what the time will be, in nanoseconds, Duration d in the future.
 // If d is negative, it is ignored. If the returned value would be less than
 // zero because of an overflow, MaxInt64 is returned.
 func when(d Duration) int64 {
 	if d <= 0 {
 		return runtimeNano()
 	}
 	t := runtimeNano() + int64(d)
 	if t < 0 {
 		// N.B. runtimeNano() and d are always positive, so addition
 		// (including overflow) will never result in t == 0.
 		t = 1<<63 - 1 // math.MaxInt64
 	}
 	return t
 }

 // These functions are pushed to package time from package runtime.

 // The arg cp is a chan Time, but the declaration in runtime uses a pointer,
 // so we use a pointer here too. This keeps some tools that aggressively
 // compare linknamed symbol definitions happier.
 //
 //go:linkname newTimer
 func newTimer(when, period int64, f func(any, uintptr, int64), arg any, cp unsafe.Pointer) *Timer

 //go:linkname stopTimer
 func stopTimer(*Timer) bool

 //go:linkname resetTimer
 func resetTimer(t *Timer, when, period int64) bool

 // Note: The runtime knows the layout of struct Timer, since newTimer allocates it.
 // The runtime also knows that Ticker and Timer have the same layout.
 // There are extra fields after the channel, reserved for the runtime
 // and inaccessible to users.

 // 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
 	initTimer bool
 }

 // Stop prevents the [Timer] from firing.
 // It returns true if the call stops the timer, false if the timer has already
 // expired or been stopped.
 //
 // For a func-based timer created with [AfterFunc](d, f),
 // if t.Stop returns false, then the timer has already expired
 // and the function f has been started in its own goroutine;
 // Stop does not wait for f to complete before returning.
 // If the caller needs to know whether f is completed,
 // it must coordinate with f explicitly.
 //
 // For a chan-based timer created with NewTimer(d), as of Go 1.23,
 // any receive from t.C after Stop has returned is guaranteed to block
 // rather than receive a stale time value from before the Stop;
 // if the program has not received from t.C already and the timer is
 // running, Stop is guaranteed to return true.
 // Before Go 1.23, the only safe way to use Stop was insert an extra
 // <-t.C if Stop returned false to drain a potential stale value.
 // See the [NewTimer] documentation for more details.
 func (t *Timer) Stop() bool {
 	if !t.initTimer {
 		panic("time: Stop called on uninitialized Timer")
 	}
 	return stopTimer(t)
 }

 // NewTimer creates a new Timer that will send
 // the current time on its channel after at least duration d.
 //
 // Before Go 1.23, the garbage collector did not recover
 // timers that had not yet expired or been stopped, so code often
 // immediately deferred t.Stop after calling NewTimer, to make
 // the timer recoverable when it was no longer needed.
 // As of Go 1.23, the garbage collector can recover unreferenced
 // timers, even if they haven't expired or been stopped.
 // The Stop method is no longer necessary to help the garbage collector.
 // (Code may of course still want to call Stop to stop the timer for other reasons.)
 //
 // Before Go 1.23, the channel associated with a Timer was
 // asynchronous (buffered, capacity 1), which meant that
 // stale time values could be received even after [Timer.Stop]
 // or [Timer.Reset] returned.
 // As of Go 1.23, the channel is synchronous (unbuffered, capacity 0),
 // eliminating the possibility of those stale values.
 //
 // The GODEBUG setting asynctimerchan=1 restores both pre-Go 1.23
 // behaviors: when set, unexpired timers won't be garbage collected, and
 // channels will have buffered capacity. This setting may be removed
 // in Go 1.27 or later.
 func NewTimer(d Duration) *Timer {
 	c := make(chan Time, 1)
 	t := (*Timer)(newTimer(when(d), 0, sendTime, c, syncTimer(c)))
 	t.C = c
 	return t
 }

 // Reset changes the timer to expire after duration d.
 // It returns true if the timer had been active, false if the timer had
 // expired or been stopped.
 //
 // For a func-based timer created with [AfterFunc](d, f), Reset either reschedules
 // when f will run, in which case Reset returns true, or schedules f
 // to run again, in which case it returns false.
 // When Reset returns false, Reset neither waits for the prior f to
 // complete before returning nor does it guarantee that the subsequent
 // goroutine running f does not run concurrently with the prior
 // one. If the caller needs to know whether the prior execution of
 // f is completed, it must coordinate with f explicitly.
 //
 // For a chan-based timer created with NewTimer, as of Go 1.23,
 // any receive from t.C after Reset has returned is guaranteed not
 // to receive a time value corresponding to the previous timer settings;
 // if the program has not received from t.C already and the timer is
 // running, Reset is guaranteed to return true.
 // Before Go 1.23, the only safe way to use Reset was to [Stop] and
 // explicitly drain the timer first.
 // See the [NewTimer] documentation for more details.
 func (t *Timer) Reset(d Duration) bool {
 	if !t.initTimer {
 		panic("time: Reset called on uninitialized Timer")
 	}
 	w := when(d)
 	return resetTimer(t, w, 0)
 }

 // sendTime does a non-blocking send of the current time on c.
 func sendTime(c any, seq uintptr, delta int64) {
 	// delta is how long ago the channel send was supposed to happen.
 	// The current time can be arbitrarily far into the future, because the runtime
 	// can delay a sendTime call until a goroutines tries to receive from
 	// the channel. Subtract delta to go back to the old time that we
 	// used to send.
 	select {
 	case c.(chan Time) <- Now().Add(Duration(-delta)):
 	default:
 	}
 }

 // After waits for the duration to elapse and then sends the current time
 // on the returned channel.
 // It is equivalent to [NewTimer](d).C.
 //
 // Before Go 1.23, this documentation warned that the underlying
 // [Timer] would not be recovered by the garbage collector until the
 // timer fired, and that if efficiency was a concern, code should use
 // NewTimer instead and call [Timer.Stop] if the timer is no longer needed.
 // As of Go 1.23, the garbage collector can recover unreferenced,
 // unstopped timers. There is no reason to prefer NewTimer when After will do.
 func After(d Duration) <-chan Time {
 	return NewTimer(d).C
 }

 // AfterFunc waits for the duration to elapse and then calls f
 // in its own goroutine. It returns a [Timer] that can
 // be used to cancel the call using its Stop method.
 // The returned Timer's C field is not used and will be nil.
 func AfterFunc(d Duration, f func()) *Timer {
 	return (*Timer)(newTimer(when(d), 0, goFunc, f, nil))
 }

 func goFunc(arg any, seq uintptr, delta int64) {
 	go arg.(func())()
 }
	// Copyright 2009 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	package time

	import (
	"internal/godebug"
	"unsafe"
	)

	// Sleep pauses the current goroutine for at least the duration d.
	// A negative or zero duration causes Sleep to return immediately.
	func Sleep(d Duration)

	var asynctimerchan = godebug.New("asynctimerchan")

	// syncTimer returns c as an unsafe.Pointer, for passing to newTimer.
	// If the GODEBUG asynctimerchan has disabled the async timer chan
	// code, then syncTimer always returns nil, to disable the special
	// channel code paths in the runtime.
	func syncTimer(c chan Time) unsafe.Pointer {
	// If asynctimerchan=1, we don't even tell the runtime
	// about channel timers, so that we get the pre-Go 1.23 code paths.
	if asynctimerchan.Value() == "1" {
	return nil
	}

	// Otherwise pass to runtime.
	// This handles asynctimerchan=0, which is the default Go 1.23 behavior,
	// as well as asynctimerchan=2, which is like asynctimerchan=1
	// but implemented entirely by the runtime.
	// The only reason to use asynctimerchan=2 is for debugging
	// a problem fixed by asynctimerchan=1: it enables the new
	// GC-able timer channels (#61542) but not the sync channels (#37196).
	//
	// If we decide to roll back the sync channels, we will still have
	// a fully tested async runtime implementation (asynctimerchan=2)
	// and can make this function always return c.
	//
	// If we decide to keep the sync channels, we can delete all the
	// handling of asynctimerchan in the runtime and keep just this
	// function to handle asynctimerchan=1.
	return (unsafe.Pointer)(unsafe.Pointer(&c))
	}

	// when is a helper function for setting the 'when' field of a runtimeTimer.
	// It returns what the time will be, in nanoseconds, Duration d in the future.
	// If d is negative, it is ignored. If the returned value would be less than
	// zero because of an overflow, MaxInt64 is returned.
	func when(d Duration) int64 {
	if d <= 0 {
	return runtimeNano()
	}
	t := runtimeNano() + int64(d)
	if t < 0 {
	// N.B. runtimeNano() and d are always positive, so addition
	// (including overflow) will never result in t == 0.
	t = 1<<63 - 1 // math.MaxInt64
	}
	return t
	}

	// These functions are pushed to package time from package runtime.

	// The arg cp is a chan Time, but the declaration in runtime uses a pointer,
	// so we use a pointer here too. This keeps some tools that aggressively
	// compare linknamed symbol definitions happier.
	//
	//go:linkname newTimer
	func newTimer(when, period int64, f func(any, uintptr, int64), arg any, cp unsafe.Pointer) *Timer

	//go:linkname stopTimer
	func stopTimer(*Timer) bool

	//go:linkname resetTimer
	func resetTimer(t *Timer, when, period int64) bool

	// Note: The runtime knows the layout of struct Timer, since newTimer allocates it.
	// The runtime also knows that Ticker and Timer have the same layout.
	// There are extra fields after the channel, reserved for the runtime
	// and inaccessible to users.

	// 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
	initTimer bool
	}

	// Stop prevents the [Timer] from firing.
	// It returns true if the call stops the timer, false if the timer has already
	// expired or been stopped.
	//
	// For a func-based timer created with [AfterFunc](d, f),
	// if t.Stop returns false, then the timer has already expired
	// and the function f has been started in its own goroutine;
	// Stop does not wait for f to complete before returning.
	// If the caller needs to know whether f is completed,
	// it must coordinate with f explicitly.
	//
	// For a chan-based timer created with NewTimer(d), as of Go 1.23,
	// any receive from t.C after Stop has returned is guaranteed to block
	// rather than receive a stale time value from before the Stop;
	// if the program has not received from t.C already and the timer is
	// running, Stop is guaranteed to return true.
	// Before Go 1.23, the only safe way to use Stop was insert an extra
	// <-t.C if Stop returned false to drain a potential stale value.
	// See the [NewTimer] documentation for more details.
	func (t *Timer) Stop() bool {
	if !t.initTimer {
	panic("time: Stop called on uninitialized Timer")
	}
	return stopTimer(t)
	}

	// NewTimer creates a new Timer that will send
	// the current time on its channel after at least duration d.
	//
	// Before Go 1.23, the garbage collector did not recover
	// timers that had not yet expired or been stopped, so code often
	// immediately deferred t.Stop after calling NewTimer, to make
	// the timer recoverable when it was no longer needed.
	// As of Go 1.23, the garbage collector can recover unreferenced
	// timers, even if they haven't expired or been stopped.
	// The Stop method is no longer necessary to help the garbage collector.
	// (Code may of course still want to call Stop to stop the timer for other reasons.)
	//
	// Before Go 1.23, the channel associated with a Timer was
	// asynchronous (buffered, capacity 1), which meant that
	// stale time values could be received even after [Timer.Stop]
	// or [Timer.Reset] returned.
	// As of Go 1.23, the channel is synchronous (unbuffered, capacity 0),
	// eliminating the possibility of those stale values.
	//
	// The GODEBUG setting asynctimerchan=1 restores both pre-Go 1.23
	// behaviors: when set, unexpired timers won't be garbage collected, and
	// channels will have buffered capacity. This setting may be removed
	// in Go 1.27 or later.
	func NewTimer(d Duration) *Timer {
	c := make(chan Time, 1)
	t := (*Timer)(newTimer(when(d), 0, sendTime, c, syncTimer(c)))
	t.C = c
	return t
	}

	// Reset changes the timer to expire after duration d.
	// It returns true if the timer had been active, false if the timer had
	// expired or been stopped.
	//
	// For a func-based timer created with [AfterFunc](d, f), Reset either reschedules
	// when f will run, in which case Reset returns true, or schedules f
	// to run again, in which case it returns false.
	// When Reset returns false, Reset neither waits for the prior f to
	// complete before returning nor does it guarantee that the subsequent
	// goroutine running f does not run concurrently with the prior
	// one. If the caller needs to know whether the prior execution of
	// f is completed, it must coordinate with f explicitly.
	//
	// For a chan-based timer created with NewTimer, as of Go 1.23,
	// any receive from t.C after Reset has returned is guaranteed not
	// to receive a time value corresponding to the previous timer settings;
	// if the program has not received from t.C already and the timer is
	// running, Reset is guaranteed to return true.
	// Before Go 1.23, the only safe way to use Reset was to [Stop] and
	// explicitly drain the timer first.
	// See the [NewTimer] documentation for more details.
	func (t *Timer) Reset(d Duration) bool {
	if !t.initTimer {
	panic("time: Reset called on uninitialized Timer")
	}
	w := when(d)
	return resetTimer(t, w, 0)
	}

	// sendTime does a non-blocking send of the current time on c.
	func sendTime(c any, seq uintptr, delta int64) {
	// delta is how long ago the channel send was supposed to happen.
	// The current time can be arbitrarily far into the future, because the runtime
	// can delay a sendTime call until a goroutines tries to receive from
	// the channel. Subtract delta to go back to the old time that we
	// used to send.
	select {
	case c.(chan Time) <- Now().Add(Duration(-delta)):
	default:
	}
	}

	// After waits for the duration to elapse and then sends the current time
	// on the returned channel.
	// It is equivalent to [NewTimer](d).C.
	//
	// Before Go 1.23, this documentation warned that the underlying
	// [Timer] would not be recovered by the garbage collector until the
	// timer fired, and that if efficiency was a concern, code should use
	// NewTimer instead and call [Timer.Stop] if the timer is no longer needed.
	// As of Go 1.23, the garbage collector can recover unreferenced,
	// unstopped timers. There is no reason to prefer NewTimer when After will do.
	func After(d Duration) <-chan Time {
	return NewTimer(d).C
	}

	// AfterFunc waits for the duration to elapse and then calls f
	// in its own goroutine. It returns a [Timer] that can
	// be used to cancel the call using its Stop method.
	// The returned Timer's C field is not used and will be nil.
	func AfterFunc(d Duration, f func()) *Timer {
	return (*Timer)(newTimer(when(d), 0, goFunc, f, nil))
	}

	func goFunc(arg any, seq uintptr, delta int64) {
	go arg.(func())()
	}