tos/lib/timer/Timer.nc

   1 //$Id$
   2
   3 /* "Copyright (c) 2000-2003 The Regents of the University of California.
   4  * All rights reserved.
   5  *
   6  * Permission to use, copy, modify, and distribute this software and its
   7  * documentation for any purpose, without fee, and without written agreement
   8  * is hereby granted, provided that the above copyright notice, the following
   9  * two paragraphs and the author appear in all copies of this software.
  10  *
  11  * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
  12  * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
  13  * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY
  14  * OF CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  15  *
  16  * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  17  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  18  * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  19  * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  20  * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
  21  */
  22
  23 #include "Timer.h"
  24
  25 /**
  26  * A Timer is TinyOS's general purpose timing interface. For more precise
  27  * timing, you may wish to use a (platform-specific) component offering
  28  * an Alarm interface.
  29  *
  30  * <p>A Timer is parameterised by its "precision" (milliseconds,
  31  * microseconds, etc), identified by a type. This prevents, e.g.,
  32  * unintentionally mixing components expecting milliseconds with those
  33  * expecting microseconds as those interfaces have a different type.
  34  *
  35  * <p>See TEP102 for more details.
  36  *
  37  * @param precision_tag A type indicating the precision of this Alarm.
  38  *
  39  * @author Cory Sharp <cssharp@eecs.berkeley.edu>
  40  */
  41
  42 interface Timer<precision_tag>
  43 {
  44   // basic interface
  45   /**
  46    * Set a periodic timer to repeat every dt time units. Replaces any
  47    * current timer settings. Equivalent to startPeriodicAt(getNow(),
  48    * dt). The <code>fired</code> will be signaled every dt units (first
  49    * event in dt units).
  50    *
  51    * @param dt Time until the timer fires.
  52    */
  53   command void startPeriodic(uint32_t dt);
  54
  55   /**
  56    * Set a single-short timer to some time units in the future. Replaces
  57    * any current timer settings. Equivalent to startOneShotAt(getNow(),
  58    * dt). The <code>fired</code> will be signaled when the timer expires.
  59    *
  60    * @param dt Time until the timer fires.
  61    */
  62   command void startOneShot(uint32_t dt);
  63
  64   /**
  65    * Cancel a timer.
  66    */
  67   command void stop();
  68
  69   /**
  70    * Signaled when the timer expires (one-shot) or repeats (periodic).
  71    */
  72   event void fired();
  73
  74   // extended interface
  75   /**
  76    * Check if timer is running. Periodic timers run until stopped or
  77    * replaced, one-shot timers run until their deadline expires.
  78    *
  79    * @return TRUE if the timer is still running.
  80    */
  81   command bool isRunning();
  82
  83   /**
  84    * Check if this is a one-shot timer.
  85    * @return TRUE for one-shot timers, FALSE for periodic timers.
  86    */
  87   command bool isOneShot();
  88
  89   /**
  90    * Set a periodic timer to repeat every dt time units. Replaces any
  91    * current timer settings. The <code>fired</code> will be signaled every
  92    * dt units (first event at t0+dt units). Periodic timers set in the past
  93    * will get a bunch of events in succession, until the timer "catches up".
  94    *
  95    * <p>Because the current time may wrap around, it is possible to use
  96    * values of t0 greater than the <code>getNow</code>'s result. These
  97    * values represent times in the past, i.e., the time at which getNow()
  98    * would last of returned that value.
  99    *
 100    * @param t0 Base time for timer.
 101    * @param dt Time until the timer fires.
 102    */
 103   command void startPeriodicAt(uint32_t t0, uint32_t dt);
 104
 105   /**
 106    * Set a single-short timer to time t0+dt. Replaces any current timer
 107    * settings. The <code>fired</code> will be signaled when the timer
 108    * expires. Timers set in the past will fire "soon".
 109    *
 110    * <p>Because the current time may wrap around, it is possible to use
 111    * values of t0 greater than the <code>getNow</code>'s result. These
 112    * values represent times in the past, i.e., the time at which getNow()
 113    * would last of returned that value.
 114    *
 115    * @param t0 Base time for timer.
 116    * @param dt Time until the timer fires.
 117    */
 118   command void startOneShotAt(uint32_t t0, uint32_t dt);
 119
 120
 121   /**
 122    * Return the current time.
 123    * @return Current time.
 124    */
 125   command uint32_t getNow();
 126
 127   /**
 128    * Return the time anchor for the previously started timer or the time of
 129    * the previous event for periodic timers. The next fired event will occur
 130    * at gett0() + getdt().
 131    * @return Timer's base time.
 132    */
 133   command uint32_t gett0();
 134
 135   /**
 136    * Return the delay or period for the previously started timer. The next
 137    * fired event will occur at gett0() + getdt().
 138    * @return Timer's interval.
 139    */
 140   command uint32_t getdt();
 141 }
 142