root/timers.h

/* */

INCLUDED FROM

   1 /* timers.h - header file for timers package
   2 **
   3 ** Copyright (c) 1995,1998,1999,2000,2014 by Jef Poskanzer <jef@mail.acme.com>.
   4 ** Copyright (c) 2023 by Amelia Zabardast Ziabari <ame@psianesia.org>.
   5 ** All rights reserved.
   6 **
   7 ** Redistribution and use in source and binary forms, with or without
   8 ** modification, are permitted provided that the following conditions
   9 ** are met:
  10 ** 1. Redistributions of source code must retain the above copyright
  11 **    notice, this list of conditions and the following disclaimer.
  12 ** 2. Redistributions in binary form must reproduce the above copyright
  13 **    notice, this list of conditions and the following disclaimer in the
  14 **    documentation and/or other materials provided with the distribution.
  15 **
  16 ** THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17 ** ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 ** IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 ** ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20 ** FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 ** DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 ** OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 ** HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 ** LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 ** OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 ** SUCH DAMAGE.
  27 */
  28 
  29 #ifndef _TIMERS_H_
  30 #define _TIMERS_H_
  31 
  32 #include <sys/time.h>
  33 #include <time.h>
  34 
  35 #ifndef INFTIM
  36 #define INFTIM -1
  37 #endif /* INFTIM */
  38 
  39 /* ClientData is a random value that tags along with a timer.  The client
  40 ** can use it for whatever, and it gets passed to the callback when the
  41 ** timer triggers.
  42 */
  43 typedef union {
  44     void* p;
  45     int i;
  46     long l;
  47     } ClientData;
  48 
  49 extern ClientData JunkClientData;       /* for use when you don't care */
  50 
  51 /* The TimerProc gets called when the timer expires.  It gets passed
  52 ** the ClientData associated with the timer, and a timeval in case
  53 ** it wants to schedule another timer.
  54 */
  55 typedef void TimerProc( ClientData client_data, struct timeval* nowP );
  56 
  57 /* The Timer struct. */
  58 typedef struct TimerStruct {
  59     TimerProc* timer_proc;
  60     ClientData client_data;
  61     long msecs;
  62     int periodic;
  63     struct timeval time;
  64     struct TimerStruct* prev;
  65     struct TimerStruct* next;
  66     int hash;
  67     } Timer;
  68 
  69 /* Initialize the timer package. */
  70 void tmr_init( void );
  71 
  72 /* Set up a timer, either periodic or one-shot. Returns (Timer*) 0 on errors. */
  73 Timer* tmr_create(
  74     struct timeval* nowP, TimerProc* timer_proc, ClientData client_data,
  75     long msecs, int periodic );
  76 
  77 /* Returns a timeout indicating how long until the next timer triggers.  You
  78 ** can just put the call to this routine right in your select().  Returns
  79 ** (struct timeval*) 0 if no timers are pending.
  80 */
  81 struct timeval* tmr_timeout( struct timeval* nowP );
  82 
  83 /* Returns a timeout in milliseconds indicating how long until the next timer
  84 ** triggers.  You can just put the call to this routine right in your poll().
  85 ** Returns INFTIM (-1) if no timers are pending.
  86 */
  87 long tmr_mstimeout( struct timeval* nowP );
  88 
  89 /* Run the list of timers. Your main program needs to call this every so often,
  90 ** or as indicated by tmr_timeout().
  91 */
  92 void tmr_run( struct timeval* nowP );
  93 
  94 /* Reset the clock on a timer, to current time plus the original timeout. */
  95 void tmr_reset( struct timeval* nowP, Timer* timer );
  96 
  97 /* Deschedule a timer.  Note that non-periodic timers are automatically
  98 ** descheduled when they run, so you don't have to call this on them.
  99 */
 100 void tmr_cancel( Timer* timer );
 101 
 102 /* Clean up the timers package, freeing any unused storage. */
 103 void tmr_cleanup( void );
 104 
 105 /* Cancel all timers and free storage, usually in preparation for exiting. */
 106 void tmr_term( void );
 107 
 108 /* Generate debugging statistics syslog message. */
 109 void tmr_logstats( long secs );
 110 
 111 /* Fill timeval structure for further usage by the package. */
 112 extern void tmr_prepare_timeval( struct timeval *tv );
 113 
 114 #endif /* _TIMERS_H_ */

/* */