Black Lives Matter. Support the Equal Justice Initiative.

Source file src/time/sleep.go

Documentation: time

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

View as plain text