Merge remote branch 'origin/andrei/cdefs2doc'
[sip-router] / timer.h
1 /*
2  * $Id$
3  *
4  *
5  * timer related functions (public interface)
6  *
7  * Copyright (C) 2001-2003 FhG Fokus
8  *
9  * This file is part of SIP-router, a free SIP server.
10  *
11  * SIP-router is free software; you can redistribute it and/or modify
12  * it under the terms of the GNU General Public License as published by
13  * the Free Software Foundation; either version 2 of the License, or
14  * (at your option) any later version
15  *
16  * SIP-router is distributed in the hope that it will be useful,
17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
19  * GNU General Public License for more details.
20  *
21  * You should have received a copy of the GNU General Public License 
22  * along with this program; if not, write to the Free Software 
23  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
24  */
25 /* History:
26  * --------
27  *  2005-07-27  complete re-design/re-implementation (andrei)
28  */
29
30 /**
31  * @file
32  * @brief SIP-router core :: timer related functions (public interface)
33  * @ingroup core
34  *
35  * Module: \ref core
36  *
37  * - \ref TimerDoc
38  */
39
40
41 /**
42  * @page TimerDoc SIP-router's timer documentation
43  * @verbinclude timers.txt
44  *
45  */
46
47
48
49 #ifndef timer_h
50 #define timer_h
51
52 #define USE_SLOW_TIMER /* use another process to run the timer handlers 
53                                                   marked "slow" */
54 /*#define TIMER_DEBUG -- compile with -DTIMER_DEBUG*/
55
56 #include "clist.h"
57 #include "dprint.h"
58 #include "timer_ticks.h"
59
60 #ifdef USE_SLOW_TIMER
61 #include <sys/types.h>
62
63 typedef unsigned short slow_idx_t; /* type fot the slow index */
64 extern pid_t slow_timer_pid;
65 #endif
66
67
68
69
70
71 /* deprecated, old, kept for compatibility */
72 typedef void (timer_function)(unsigned int ticks, void* param);
73 /* deprecated, old, kept for compatibility 
74         get_ticks()*TIMER_TICK used to be the time in s
75         for new code, use get_ticks_raw() and one of the macros defined in
76         time_ticks.h (.e.g TICKS_TO_S(tick) to convert to s or ms )*/
77 #define TIMER_TICK 1 /* 1 s, kept for compatibility */
78
79
80 struct timer_ln; /* forward decl */
81 /* new 
82  * params:
83  *         - handle pointer to the corresponding struct timer_ln
84  * return: 0 if the timer is one shot, new expire interval if not, -1
85  *         if periodic
86  * e.g.:   - a periodic timer would return: (ticks_t)(-1) or
87  *            ((struct timer_ln*)handle)->initial_timeout
88  *         - a timer which wants to expire again in x ms would return:
89  *             (x * TICKS_HZ + 999)/1000
90  */
91 typedef ticks_t (timer_handler_f)(ticks_t t, struct timer_ln* tl,
92                                                                         void* data);
93
94
95 /* timer flags */
96 #define F_TIMER_FAST    1
97 #define F_TIMER_ON_SLOW_LIST    0x100
98 #define F_TIMER_ACTIVE  0x200 /* timer is running or has run and expired
99                                                                  (one shot) */
100 #ifdef TIMER_DEBUG
101 #define F_TIMER_DELETED 0x400 
102 #endif
103
104 struct timer_ln{ /* timer_link already used in tm */
105         struct timer_ln* next;
106         struct timer_ln* prev;
107         ticks_t expire; 
108         ticks_t initial_timeout;
109         void* data;
110         timer_handler_f* f; 
111         volatile unsigned short flags;
112 #ifdef USE_SLOW_TIMER
113         volatile slow_idx_t slow_idx;
114 #else
115         unsigned short reserved;
116 #endif
117 #ifdef TIMER_DEBUG
118         unsigned int expires_no; /* timer handler calls */
119         const char* add_file;
120         const char* add_func;
121         unsigned add_line;
122         unsigned add_calls;
123         const char* del_file;
124         const char* del_func;
125         unsigned del_line;
126         unsigned int del_calls;
127         unsigned int init; /* how many times was init/re-init */
128 #endif
129 };
130
131
132
133 void timer_main(); /* timer main loop, never exists */
134
135
136 int init_timer();
137 int arm_timer();
138 void destroy_timer();
139
140 #ifdef USE_SLOW_TIMER
141 int arm_slow_timer();
142 void slow_timer_main();
143 #endif
144
145
146 struct timer_ln* timer_alloc();
147 void timer_free(struct timer_ln* t);
148
149 #ifdef TIMER_DEBUG
150 /* use for a deleted/expired timer that you want to add again */
151 #define timer_reinit(tl) \
152         do{ \
153                 (tl)->flags&=~((unsigned short)(F_TIMER_ON_SLOW_LIST | \
154                                                                                           F_TIMER_ACTIVE));\
155                 (tl)->init++; \
156         }while(0)
157 #else
158 /* use for a deleted/expired timer that you want to add again */
159 #define timer_reinit(tl) \
160         (tl)->flags&=~((unsigned short)(F_TIMER_ON_SLOW_LIST | \
161                                                                                   F_TIMER_ACTIVE))
162 #endif
163
164 #define timer_init(tl, fun, param, flgs) \
165         do{ \
166                 memset((tl), 0, sizeof(struct timer_ln)); \
167                 (tl)->f=(fun); \
168                 (tl)->data=(param); \
169                 (tl)->flags=(flgs); \
170                 timer_reinit(tl); \
171         }while(0)
172
173 #ifdef TIMER_DEBUG
174 int timer_add_safe(struct timer_ln *tl, ticks_t delta, 
175                                         const char*, const char*, unsigned);
176 int timer_del_safe(struct timer_ln *tl,
177                                         const char*, const char*, unsigned);
178 #define timer_add(tl, d) \
179         timer_add_safe((tl), (d), __FILE__, __FUNCTION__, __LINE__)
180 #define timer_del(tl) \
181         timer_del_safe((tl), __FILE__, __FUNCTION__, __LINE__)
182 #else
183 int timer_add_safe(struct timer_ln *tl, ticks_t delta);
184 int timer_del_safe(struct timer_ln *tl);
185 #define timer_add timer_add_safe
186 #define timer_del timer_del_safe
187 #endif
188
189 void timer_allow_del();
190
191 /* old timer compatibility functions & structure */
192
193 struct sr_timer{
194         struct timer_ln tl;
195         int id;
196         timer_function* timer_f;
197         void* t_param;
198 };
199
200
201 /*register a periodic timer;
202  * ret: <0 on error*/
203 int register_timer(timer_function f, void* param, unsigned int interval);
204 ticks_t get_ticks();
205 ticks_t get_ticks_raw();
206
207 #endif