libgo/go/time/tick.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 import "errors"
   8
   9 // A Ticker holds a channel that delivers `ticks' of a clock
  10 // at intervals.
  11 type Ticker struct {
  12         C <-chan Time // The channel on which the ticks are delivered.
  13         r runtimeTimer
  14 }
  15
  16 // NewTicker returns a new Ticker containing a channel that will send the
  17 // time with a period specified by the duration argument.
  18 // It adjusts the intervals or drops ticks to make up for slow receivers.
  19 // The duration d must be greater than zero; if not, NewTicker will panic.
  20 // Stop the ticker to release associated resources.
  21 func NewTicker(d Duration) *Ticker {
  22         if d <= 0 {
  23                 panic(errors.New("non-positive interval for NewTicker"))
  24         }
  25         // Give the channel a 1-element time buffer.
  26         // If the client falls behind while reading, we drop ticks
  27         // on the floor until the client catches up.
  28         c := make(chan Time, 1)
  29         t := &Ticker{
  30                 C: c,
  31                 r: runtimeTimer{
  32                         when:   when(d),
  33                         period: int64(d),
  34                         f:      sendTime,
  35                         arg:    c,
  36                 },
  37         }
  38         startTimer(&t.r)
  39         return t
  40 }
  41
  42 // Stop turns off a ticker.  After Stop, no more ticks will be sent.
  43 // Stop does not close the channel, to prevent a read from the channel succeeding
  44 // incorrectly.
  45 func (t *Ticker) Stop() {
  46         stopTimer(&t.r)
  47 }
  48
  49 // Tick is a convenience wrapper for NewTicker providing access to the ticking
  50 // channel only.  Useful for clients that have no need to shut down the ticker.
  51 func Tick(d Duration) <-chan Time {
  52         if d <= 0 {
  53                 return nil
  54         }
  55         return NewTicker(d).C
  56 }