parser/sdp: more suggestive debug message
[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         timer_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 /*function prototype to execute on mili-second based basic timers */
80 typedef void (utimer_function)(unsigned int uticks, void* param);
81
82 struct timer_ln; /* forward decl */
83 /* new 
84  * params:
85  *         - handle pointer to the corresponding struct timer_ln
86  * return: 0 if the timer is one shot, new expire interval if not, -1
87  *         if periodic
88  * e.g.:   - a periodic timer would return: (ticks_t)(-1) or
89  *            ((struct timer_ln*)handle)->initial_timeout
90  *         - a timer which wants to expire again in x ms would return:
91  *             (x * TICKS_HZ + 999)/1000
92  */
93 typedef ticks_t (timer_handler_f)(ticks_t t, struct timer_ln* tl,
94                                                                         void* data);
95
96
97 /* timer flags */
98 #define F_TIMER_FAST    1
99 #define F_TIMER_ON_SLOW_LIST    0x100
100 #define F_TIMER_ACTIVE  0x200 /* timer is running or has run and expired
101                                                                  (one shot) */
102 #ifdef TIMER_DEBUG
103 #define F_TIMER_DELETED 0x400 
104 #endif
105
106 struct timer_ln{ /* timer_link already used in tm */
107         struct timer_ln* next;
108         struct timer_ln* prev;
109         ticks_t expire; 
110         ticks_t initial_timeout;
111         void* data;
112         timer_handler_f* f; 
113         volatile unsigned short flags;
114 #ifdef USE_SLOW_TIMER
115         volatile slow_idx_t slow_idx;
116 #else
117         unsigned short reserved;
118 #endif
119 #ifdef TIMER_DEBUG
120         unsigned int expires_no; /* timer handler calls */
121         const char* add_file;
122         const char* add_func;
123         unsigned add_line;
124         unsigned add_calls;
125         const char* del_file;
126         const char* del_func;
127         unsigned del_line;
128         unsigned int del_calls;
129         unsigned int init; /* how many times was init/re-init */
130 #endif
131 };
132
133
134
135 void timer_main(void); /* timer main loop, never exists */
136
137
138 int init_timer(void);
139 int arm_timer(void);
140 void destroy_timer(void);
141
142 #ifdef USE_SLOW_TIMER
143 int arm_slow_timer(void);
144 void slow_timer_main(void);
145 #endif
146
147
148 struct timer_ln* timer_alloc(void);
149 void timer_free(struct timer_ln* t);
150
151 #ifdef TIMER_DEBUG
152 /* use for a deleted/expired timer that you want to add again */
153 #define timer_reinit(tl) \
154         do{ \
155                 (tl)->flags&=~((unsigned short)(F_TIMER_ON_SLOW_LIST | \
156                                                                                           F_TIMER_ACTIVE));\
157                 (tl)->init++; \
158         }while(0)
159 #else
160 /* use for a deleted/expired timer that you want to add again */
161 #define timer_reinit(tl) \
162         (tl)->flags&=~((unsigned short)(F_TIMER_ON_SLOW_LIST | \
163                                                                                   F_TIMER_ACTIVE))
164 #endif
165
166 #define timer_init(tl, fun, param, flgs) \
167         do{ \
168                 memset((tl), 0, sizeof(struct timer_ln)); \
169                 (tl)->f=(fun); \
170                 (tl)->data=(param); \
171                 (tl)->flags=(flgs); \
172                 timer_reinit(tl); \
173         }while(0)
174
175 #ifdef TIMER_DEBUG
176 int timer_add_safe(struct timer_ln *tl, ticks_t delta, 
177                                         const char*, const char*, unsigned);
178 int timer_del_safe(struct timer_ln *tl,
179                                         const char*, const char*, unsigned);
180 #define timer_add(tl, d) \
181         timer_add_safe((tl), (d), __FILE__, __FUNCTION__, __LINE__)
182 #define timer_del(tl) \
183         timer_del_safe((tl), __FILE__, __FUNCTION__, __LINE__)
184 #else
185 int timer_add_safe(struct timer_ln *tl, ticks_t delta);
186 int timer_del_safe(struct timer_ln *tl);
187 #define timer_add timer_add_safe
188 #define timer_del timer_del_safe
189 #endif
190
191 void timer_allow_del(void);
192
193 /* old timer compatibility functions & structure */
194
195 struct sr_timer{
196         struct timer_ln tl;
197         int id;
198         timer_function* timer_f;
199         void* t_param;
200 };
201
202
203 /*register a periodic timer;
204  * ret: <0 on error*/
205 int register_timer(timer_function f, void* param, unsigned int interval);
206 ticks_t get_ticks(void);
207 ticks_t get_ticks_raw(void);
208
209 #endif