1 // Copyright 2009 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package time 6 7 // Sleep pauses the current goroutine for at least the duration d. 8 // A negative or zero duration causes Sleep to return immediately. 9 func Sleep(d Duration) 10 11 // Interface to timers implemented in package runtime. 12 // Must be in sync with ../runtime/time.go:/^type timer 13 type runtimeTimer struct { 14 tb uintptr 15 i int 16 17 when int64 18 period int64 19 f func(interface{}, uintptr) // NOTE: must not be closure 20 arg interface{} 21 seq uintptr 22 } 23 24 // when is a helper function for setting the 'when' field of a runtimeTimer. 25 // It returns what the time will be, in nanoseconds, Duration d in the future. 26 // If d is negative, it is ignored. If the returned value would be less than 27 // zero because of an overflow, MaxInt64 is returned. 28 func when(d Duration) int64 { 29 if d <= 0 { 30 return runtimeNano() 31 } 32 t := runtimeNano() + int64(d) 33 if t < 0 { 34 t = 1<<63 - 1 // math.MaxInt64 35 } 36 return t 37 } 38 39 func startTimer(*runtimeTimer) 40 func stopTimer(*runtimeTimer) bool 41 42 // The Timer type represents a single event. 43 // When the Timer expires, the current time will be sent on C, 44 // unless the Timer was created by AfterFunc. 45 // A Timer must be created with NewTimer or AfterFunc. 46 type Timer struct { 47 C <-chan Time 48 r runtimeTimer 49 } 50 51 // Stop prevents the Timer from firing. 52 // It returns true if the call stops the timer, false if the timer has already 53 // expired or been stopped. 54 // Stop does not close the channel, to prevent a read from the channel succeeding 55 // incorrectly. 56 // 57 // To ensure the channel is empty after a call to Stop, check the 58 // return value and drain the channel. 59 // For example, assuming the program has not received from t.C already: 60 // 61 // if !t.Stop() { 62 // <-t.C 63 // } 64 // 65 // This cannot be done concurrent to other receives from the Timer's 66 // channel. 67 // 68 // For a timer created with AfterFunc(d, f), if t.Stop returns false, then the timer 69 // has already expired and the function f has been started in its own goroutine; 70 // Stop does not wait for f to complete before returning. 71 // If the caller needs to know whether f is completed, it must coordinate 72 // with f explicitly. 73 func (t *Timer) Stop() bool { 74 if t.r.f == nil { 75 panic("time: Stop called on uninitialized Timer") 76 } 77 return stopTimer(&t.r) 78 } 79 80 // NewTimer creates a new Timer that will send 81 // the current time on its channel after at least duration d. 82 func NewTimer(d Duration) *Timer { 83 c := make(chan Time, 1) 84 t := &Timer{ 85 C: c, 86 r: runtimeTimer{ 87 when: when(d), 88 f: sendTime, 89 arg: c, 90 }, 91 } 92 startTimer(&t.r) 93 return t 94 } 95 96 // Reset changes the timer to expire after duration d. 97 // It returns true if the timer had been active, false if the timer had 98 // expired or been stopped. 99 // 100 // Reset should be invoked only on stopped or expired timers with drained channels. 101 // If a program has already received a value from t.C, the timer is known 102 // to have expired and the channel drained, so t.Reset can be used directly. 103 // If a program has not yet received a value from t.C, however, 104 // the timer must be stopped and—if Stop reports that the timer expired 105 // before being stopped—the channel explicitly drained: 106 // 107 // if !t.Stop() { 108 // <-t.C 109 // } 110 // t.Reset(d) 111 // 112 // This should not be done concurrent to other receives from the Timer's 113 // channel. 114 // 115 // Note that it is not possible to use Reset's return value correctly, as there 116 // is a race condition between draining the channel and the new timer expiring. 117 // Reset should always be invoked on stopped or expired channels, as described above. 118 // The return value exists to preserve compatibility with existing programs. 119 func (t *Timer) Reset(d Duration) bool { 120 if t.r.f == nil { 121 panic("time: Reset called on uninitialized Timer") 122 } 123 w := when(d) 124 active := stopTimer(&t.r) 125 t.r.when = w 126 startTimer(&t.r) 127 return active 128 } 129 130 func sendTime(c interface{}, seq uintptr) { 131 // Non-blocking send of time on c. 132 // Used in NewTimer, it cannot block anyway (buffer). 133 // Used in NewTicker, dropping sends on the floor is 134 // the desired behavior when the reader gets behind, 135 // because the sends are periodic. 136 select { 137 case c.(chan Time) <- Now(): 138 default: 139 } 140 } 141 142 // After waits for the duration to elapse and then sends the current time 143 // on the returned channel. 144 // It is equivalent to NewTimer(d).C. 145 // The underlying Timer is not recovered by the garbage collector 146 // until the timer fires. If efficiency is a concern, use NewTimer 147 // instead and call Timer.Stop if the timer is no longer needed. 148 func After(d Duration) <-chan Time { 149 return NewTimer(d).C 150 } 151 152 // AfterFunc waits for the duration to elapse and then calls f 153 // in its own goroutine. It returns a Timer that can 154 // be used to cancel the call using its Stop method. 155 func AfterFunc(d Duration, f func()) *Timer { 156 t := &Timer{ 157 r: runtimeTimer{ 158 when: when(d), 159 f: goFunc, 160 arg: f, 161 }, 162 } 163 startTimer(&t.r) 164 return t 165 } 166 167 func goFunc(arg interface{}, seq uintptr) { 168 go arg.(func())() 169 } 170