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