etimer.h

Go to the documentation of this file.
00001 /** \addtogroup sys
00002  * @{ */
00003 
00004 /**
00005  * \defgroup etimer Event timers
00006  *
00007  * Event timers provides a way to generate timed events. An event
00008  * timer will post an event to the process that set the timer when the
00009  * event timer expires.
00010  *
00011  * An event timer is declared as a \c struct \c etimer and all access
00012  * to the event timer is made by a pointer to the declared event
00013  * timer.
00014  *
00015  * \sa \ref timer "Simple timer library"
00016  * \sa \ref clock "Clock library" (used by the timer library)
00017  *
00018  * @{
00019  */
00020 
00021 
00022 /**
00023  * \file
00024  * Event timer header file.
00025  * \author
00026  * Adam Dunkels <adam@sics.se>
00027  */
00028 
00029 /*
00030  * Copyright (c) 2004, Swedish Institute of Computer Science.
00031  * All rights reserved.
00032  *
00033  * Redistribution and use in source and binary forms, with or without
00034  * modification, are permitted provided that the following conditions
00035  * are met:
00036  * 1. Redistributions of source code must retain the above copyright
00037  *    notice, this list of conditions and the following disclaimer.
00038  * 2. Redistributions in binary form must reproduce the above copyright
00039  *    notice, this list of conditions and the following disclaimer in the
00040  *    documentation and/or other materials provided with the distribution.
00041  * 3. Neither the name of the Institute nor the names of its contributors
00042  *    may be used to endorse or promote products derived from this software
00043  *    without specific prior written permission.
00044  *
00045  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00046  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00047  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00048  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00049  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00050  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00051  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00052  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00053  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00054  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00055  * SUCH DAMAGE.
00056  *
00057  * This file is part of the Contiki operating system.
00058  *
00059  * Author: Adam Dunkels <adam@sics.se>
00060  *
00061  * $Id: etimer.h,v 1.3 2008/02/07 23:04:35 oliverschmidt Exp $
00062  */
00063 #ifndef __ETIMER_H__
00064 #define __ETIMER_H__
00065 
00066 #include "sys/timer.h"
00067 #include "sys/process.h"
00068 
00069 /**
00070  * A timer.
00071  *
00072  * This structure is used for declaring a timer. The timer must be set
00073  * with etimer_set() before it can be used.
00074  *
00075  * \hideinitializer
00076  */
00077 struct etimer {
00078   struct timer timer;
00079   struct etimer *next;
00080   struct process *p;
00081 };
00082 
00083 /**
00084  * \name Functions called from application programs
00085  * @{
00086  */
00087 
00088 /**
00089  * \brief      Set an event timer.
00090  * \param et   A pointer to the event timer
00091  * \param interval The interval before the timer expires.
00092  *
00093  *             This function is used to set an event timer for a time
00094  *             sometime in the future. When the event timer expires,
00095  *             the event PROCESS_EVENT_TIMER will be posted to the
00096  *             process that called the etimer_set() function.
00097  *
00098  */
00099 CCIF void etimer_set(struct etimer *et, clock_time_t interval);
00100 
00101 /**
00102  * \brief      Reset an event timer with the same interval as was
00103  *             previously set.
00104  * \param et   A pointer to the event timer.
00105  *
00106  *             This function resets the event timer with the same
00107  *             interval that was given to the event timer with the
00108  *             etimer_set() function. The start point of the interval
00109  *             is the exact time that the event timer last
00110  *             expired. Therefore, this function will cause the timer
00111  *             to be stable over time, unlike the etimer_restart()
00112  *             function.
00113  *
00114  * \sa etimer_restart()
00115  */
00116 CCIF void etimer_reset(struct etimer *et);
00117 
00118 /**
00119  * \brief      Restart an event timer from the current point in time
00120  * \param et   A pointer to the event timer.
00121  *
00122  *             This function restarts the event timer with the same
00123  *             interval that was given to the etimer_set()
00124  *             function. The event timer will start at the current
00125  *             time.
00126  *
00127  *             \note A periodic timer will drift if this function is
00128  *             used to reset it. For periodic timers, use the
00129  *             etimer_reset() function instead.
00130  *
00131  * \sa etimer_reset()
00132  */
00133 void etimer_restart(struct etimer *et);
00134 
00135 /**
00136  * \brief      Adjust the expiration time for an event timer
00137  * \param et   A pointer to the event timer.
00138  * \param td   The time difference to adjust the expiration time with.
00139  *
00140  *             This function is used to adjust the time the event
00141  *             timer will expire. It can be used to synchronize
00142  *             periodic timers without the need to restart the timer
00143  *             or change the timer interval.
00144  *
00145  *             \note This function should only be used for small
00146  *             adjustments. For large adjustments use etimer_set()
00147  *             instead.
00148  *
00149  *             \note A periodic timer will drift unless the
00150  *             etimer_reset() function is used.
00151  *
00152  * \sa etimer_set()
00153  * \sa etimer_reset()
00154  */
00155 void etimer_adjust(struct etimer *et, int td);
00156 
00157 /**
00158  * \brief      Get the expiration time for the event timer.
00159  * \param et   A pointer to the event timer
00160  * \return     The expiration time for the event timer.
00161  *
00162  *             This function returns the expiration time for an event timer.
00163  */
00164 clock_time_t etimer_expiration_time(struct etimer *et);
00165 
00166 /**
00167  * \brief      Get the start time for the event timer.
00168  * \param et   A pointer to the event timer
00169  * \return     The start time for the event timer.
00170  *
00171  *             This function returns the start time (when the timer
00172  *             was last set) for an event timer.
00173  */
00174 clock_time_t etimer_start_time(struct etimer *et);
00175 
00176 /**
00177  * \brief      Check if an event timer has expired.
00178  * \param et   A pointer to the event timer
00179  * \return     Non-zero if the timer has expired, zero otherwise.
00180  *
00181  *             This function tests if an event timer has expired and
00182  *             returns true or false depending on its status.
00183  */
00184 CCIF int etimer_expired(struct etimer *et);
00185 
00186 /**
00187  * \brief      Stop a pending event timer.
00188  * \param et   A pointer to the pending event timer.
00189  *
00190  *             This function stops an event timer that has previously
00191  *             been set with etimer_set() or etimer_reset(). After
00192  *             this function has been called, the event timer will not
00193  *             emit any event when it expires.
00194  *
00195  */
00196 void etimer_stop(struct etimer *et);
00197 
00198 /** @} */
00199 
00200 /**
00201  * \name Functions called from timer interrupts, by the system
00202  * @{
00203  */
00204 
00205 /**
00206  * \brief      Make the event timer aware that the clock has changed
00207  *
00208  *             This function is used to inform the event timer module
00209  *             that the system clock has been updated. Typically, this
00210  *             function would be called from the timer interrupt
00211  *             handler when the clock has ticked.
00212  */
00213 void etimer_request_poll(void);
00214 
00215 /**
00216  * \brief      Check if there are any non-expired event timers.
00217  * \return     True if there are active event timers, false if there are
00218  *             no active timers.
00219  *
00220  *             This function checks if there are any active event
00221  *             timers that have not expired.
00222  */
00223 int etimer_pending(void);
00224 
00225 /**
00226  * \brief      Get next event timer expiration time.
00227  * \return     Next expiration time of all pending event timers.
00228  *             If there are no pending event timers this function
00229  *             returns 0.
00230  *
00231  *             This functions returns next expiration time of all
00232  *             pending event timers.
00233  */
00234 clock_time_t etimer_next_expiration_time(void);
00235 
00236 
00237 /** @} */
00238 
00239 PROCESS_NAME(etimer_process);
00240 #endif /* __ETIMER_H__ */
00241 /** @} */
00242 /** @} */

Generated on Mon Apr 11 14:23:33 2011 for Contiki 2.5 by  doxygen 1.6.1