libgo/go/time/sleep.go

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