Debian Codegraph @

src/modules/ptimer/README

raw
1 Ptimer Module
2
3 Tyler Moore
4
5 dOpenSource
6 <[email protected]>
7
8 Edited by
9
10 Tyler Moore
11
12 dOpenSource
13 <[email protected]>
14
15 Copyright © 2025 Tyler Moore, dOpenSource
16 __________________________________________________________________
17
18 Table of Contents
19
20 1. Admin Guide
21
22 1. Overview
23 2. Dependencies
24
25 2.1. Module Dependencies
26 2.2. External Dependencies
27
28 3. Parameters
29
30 3.1. default_type (int)
31 3.2. default_interval (str)
32 3.3. default_nworkers (int)
33 3.4. timer (str)
34 3.5. start (str)
35 3.6. loop (str)
36 3.7. end (str)
37
38 4. Pseudo Variables
39
40 4.1. $ptimer(...)
41
42 5. RPC Commands
43
44 5.1. ptimer.list
45 5.2. ptimer.pause
46 5.3. ptimer.continue
47 5.4. ptimer.start
48 5.5. ptimer.loop
49 5.6. ptimer.end
50
51 6. Example Usages
52
53 6.1. Call Rate Shaping
54
55 6.1.1. Global Traffic Shaping
56 6.1.2. Per Customer Traffic Shaping
57
58 6.2. Adaptive Routing
59 6.3. Dynamic Timers
60
61 6.3.1. Queue Control
62 6.3.2. Hot-Reload Tasks
63
64 Chapter 1. Admin Guide
65
66 Table of Contents
67
68 1. Overview
69 2. Dependencies
70
71 2.1. Module Dependencies
72 2.2. External Dependencies
73
74 3. Parameters
75
76 3.1. default_type (int)
77 3.2. default_interval (str)
78 3.3. default_nworkers (int)
79 3.4. timer (str)
80 3.5. start (str)
81 3.6. loop (str)
82 3.7. end (str)
83
84 4. Pseudo Variables
85
86 4.1. $ptimer(...)
87
88 5. RPC Commands
89
90 5.1. ptimer.list
91 5.2. ptimer.pause
92 5.3. ptimer.continue
93 5.4. ptimer.start
94 5.5. ptimer.loop
95 5.6. ptimer.end
96
97 6. Example Usages
98
99 6.1. Call Rate Shaping
100
101 6.1.1. Global Traffic Shaping
102 6.1.2. Per Customer Traffic Shaping
103
104 6.2. Adaptive Routing
105 6.3. Dynamic Timers
106
107 6.3.1. Queue Control
108 6.3.2. Hot-Reload Tasks
109
110 1. Overview
111
112 This module implements precise timers, which are not limited in
113 precision by the kamailio tick frequency.
114
115 All timers in this module are implemented as background processes,
116 using system time for synchronization.
117
118 Each timer can have 3 config routes associated with it:
119 * start - the route to execute when the timer starts
120 * loop - the route to execute continuously (every interval)
121 * end - the route to execute when the timer ends
122
123 A faked SIP message is given as parameter to called functions, so all
124 functions available for REQUEST_ROUTE can be used. Additionally, the
125 message state is preserved from start to end of the timer.
126
127 2. Dependencies
128
129 2.1. Module Dependencies
130 2.2. External Dependencies
131
132 2.1. Module Dependencies
133
134 The following modules must be loaded before this module:
135 * No dependencies on other Kamailio modules.
136
137 2.2. External Dependencies
138
139 The following libraries or applications must be installed before
140 running Kamailio with this module loaded:
141 * None.
142
143 3. Parameters
144
145 3.1. default_type (int)
146 3.2. default_interval (str)
147 3.3. default_nworkers (int)
148 3.4. timer (str)
149 3.5. start (str)
150 3.6. loop (str)
151 3.7. end (str)
152
153 3.1. default_type (int)
154
155 The default timer type (if not present on the "timer" parameter).
156
157 If not set, defaults to 1, basic timers.
158
159 Can be one of:
160 * 0 - basic timer A simple sleep / execute timer.
161 * 1 - sync timer Synchronizes time each loop, accounting for
162 execution time drift. This type of timer will use a nanosecond
163 precision time functions when sleeping / syncing, and the interval
164 will be scaled for you.
165 * 2 - slice timer A basic timer that slices given tasks into chunks
166 for each loop iteration. The current slice and number of tasks are
167 available via the pseudo variables. Tasks are split using an
168 interval splitting algorithm:
169 tasks(i) = ⌊((i + 1) * n) / k⌋ − ⌊(i * n) / k⌋
170 Where, n = total tasks, k = number of slices, and i = current slice
171 index. For simplicity, the number of tasks assigned to each worker
172 is roughly:
173 tasks = n / k
174 with the integer remainder evenly distributed. Further slicing per
175 worker is possible within the start the route.
176 * 3 - synced slice timer This type of timer combines the
177 functionality of a sync timer and slice timer.
178
179 Example: set default_type parameter
180 ...
181
182 # set the default type to basic timers
183 modparam("ptimer", "default_type", 0)
184 # set the default type to sync timers
185 modparam("ptimer", "default_type", 1)
186 # set the default type to slice timers
187 modparam("ptimer", "default_type", 2)
188 # set the default type to synced slice timers
189 modparam("ptimer", "default_type", 3)
190
191 ...
192
193 3.2. default_interval (str)
194
195 The default interval to execute loop route for timers (if not present
196 on the "timer" parameter). Suffix with "s", "ms", or "us" for an
197 interval in seconds, milliseconds, or microseconds. If a number is
198 given without a suffix, the number will be treated as seconds. Defaults
199 to default_interval.
200
201 If not set, defaults to 1s.
202
203 Example: set default_interval parameter
204 ...
205
206 # set the default interval to 300 seconds
207 modparam("ptimer", "default_interval", "300")
208 # set the default interval to 10 seconds
209 modparam("ptimer", "default_interval", "10s")
210 # set the default interval to 10 milliseconds
211 modparam("ptimer", "default_interval", 100ms)
212 # set the default interval to 100 microseconds
213 modparam("ptimer", "default_interval", 10ous)
214
215 ...
216
217 3.3. default_nworkers (int)
218
219 The default number of workers to run per timer (if not present on the
220 "timer" parameter).
221
222 Example: set default_nworkers parameter
223 ...
224
225 # set the default number of timer workers to 8
226 modparam("ptimer", "default_nworkers", 8)
227
228 ...
229
230 3.4. timer (str)
231
232 The definition of a timer. The value of the parameter must have the
233 following format:
234 * "name=_str_;type=_int_;interval=_str_;nworkers=_int_;ntasks=_int_;n
235 slices=_int_"
236
237 The parameter can be set multiple times to define more timers in same
238 configuration file.
239 * name - name of the timer. This attribute is required.
240 * type - type of timer to use (see default_type for more info). This
241 attribute is optional, defaults to default_type.
242 * interval - interval at which the timer workers will execute the
243 loop route. See default_interval for more information.
244 * nworkers - the number of worker processes to spawn for this timer.
245 Defaults to default_nworkers.
246 * ntasks - number of tasks each worker will process. If static, you
247 can use this parameter, otherwise you can set it within the start
248 route. This attribute is optional.
249 * nslices - number of slices to split ntasks into. This attribute,
250 although set on other timers, only effects tasks when used on a
251 slice timer.
252
253 Example: set timer parameter
254 ...
255
256 # basic timer looping every 1 sec
257 modparam("ptimer", "timer", "name=t1;interval=1s;type=0")
258 # sync timer that processes 25 tasks every 100 ms
259 modparam("ptimer", "timer", "name=t2;interval=100ms;type=1;ntasks=25")
260 # slice timer that processes 10% of the tasks from queue of 2500 every 10 sec
261 modparam("ptimer", "timer", "name=t3;interval=10s;type=2;nslices=10;ntasks=2500"
262 )
263 # basic timer that runs the loop route on 8 different worker processes every 100
264 us
265 modparam("ptimer", "timer", "name=t4;interval=100us;type=1;nworkers=8")
266
267 ...
268
269 3.5. start (str)
270
271 Route to be executed when timer stars. The value of the parameter must
272 have the following format:
273 * "timer=_str_;route=_str_"
274
275 The start route is optional, only one start route can be set per timer.
276 * timer - name of the timer.
277 * route - the name of the route block to be executed, or the name of
278 the function from kemi script. The kemi function receives a string
279 parameter with the value being the name of the module.
280
281 The start route is the typical place to put code that sets up for the
282 loop route. One can modify some of the pseudo variables in this route,
283 such as ntasks. Dynamic or external values can be obtained and stored
284 here, i.e. from an htable, database, etc... Variables and AVPs set here
285 will remain in-tact in the subsequent loop and end routes. If the start
286 route returns -1 the timer will jump execution to the end route.
287
288 Example: set start parameter
289 ...
290
291 modparam("ptimer", "timer", "name=t1;interval=10")
292 modparam("ptimer", "start", "timer=t1;route=TIMER_START")
293 modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP")
294
295 route[TIMER_START] {
296 $ptimer(ntasks) = 1000;
297 }
298
299 ...
300
301 route[TIMER_LOOP] {
302 $var(i) = 0;
303 while($var(i) < $ptimer(ntasks)) {
304 xlog("L_INFO", "handled task $var(i)\n");
305 $var(i) = $var(i) + 1;
306 }
307 }
308
309 ...
310
311 3.6. loop (str)
312
313 Route to be executed on timer interval. The value of the parameter must
314 have the following format:
315 * "timer=_str_;route=_str_"
316
317 Each timer requires a loop route, only one loop route can be set per
318 timer.
319 * timer - name of the timer.
320 * route - the name of the route block to be executed, or the name of
321 the function from kemi script. The kemi function receives a string
322 parameter with the value being the name of the module.
323
324 The loop route is executed every interval, continuously. This is
325 typically where you would process the tasks. If the loop route returns
326 -1 the timer will jump execution to the end route.
327
328 Example: set loop parameter
329 ...
330
331 modparam("ptimer", "timer", "name=t1;interval=10")
332 modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP")
333
334 ...
335
336 route[TIMER_LOOP] {
337 xlog("L_INFO", "timer $ptimer(name) executed at $TF\n");
338 }
339
340 ...
341
342 Example: use loop parameter with Kemi engine
343 ...
344
345 modparam("ptimer", "timer", "name=t1;interval=10")
346 modparam("ptimer", "loop", "timer=t1;route=timer_loop")
347
348 ...
349
350 -- ptimer event callback function implemented in Lua
351 function timer_loop(evname)
352 KSR.info("===== ptimer module triggered event\n");
353 return 1;
354 end
355
356 ...
357
358 3.7. end (str)
359
360 Route to be executed when timer ends. The value of the parameter must
361 have the following format:
362 * "timer=_str_;route=_str_"
363
364 The end route is optional, only one end route can be set per timer.
365 * timer - name of the timer.
366 * route - the name of the route block to be executed, or the name of
367 the function from kemi script. The kemi function receives a string
368 parameter with the value being the name of the module.
369
370 The end route runs after the timer ends. Typically this would the place
371 to lgog or store data about the tasks processed. After the end route
372 completes, the environment is cleared, and the worker is paused.
373
374 Example: set end parameter
375 ...
376
377 modparam("ptimer", "timer", "name=t1;interval=100ms")
378 modparam("ptimer", "start", "timer=t1;route=TIMER_START")
379 modparam("ptimer", "loop", "timer=t1;route=TIMER_LOOP")
380 modparam("ptimer", "end", "timer=t1;route=TIMER_END")
381
382 ...
383
384 route[TIMER_START] {
385 $var(tasks_done) = 0;
386 }
387
388 route[TIMER_LOOP] {
389 $var(tasks_done) = $var(tasks_done) + 1;
390 }
391
392 route[TIMER_END] {
393 xlog("L_INFO", "tasks handled $var(tasks_done)\n");
394 }
395
396 ...
397
398 4. Pseudo Variables
399
400 4.1. $ptimer(...)
401
402 4.1. $ptimer(...)
403
404 Access to timer / worker attributes.
405
406 This PV is only available within ptimer executed routes.
407
408 The following attributes are available:
409 * name - name of the timer executing this route. This attribute is
410 read-only.
411 * type - type of timer executing this route. This attribute is
412 read-only.
413 * interval - interval for this timer. This attribute is r/w inside
414 the start route, and r/o elsewhere.
415 * nworkers - number of workers spawned for this timer. This attribute
416 is read-only.
417 * worker - current worker processing this route. This attribute is
418 read-only.
419 * pid - pid of current worker processing this route. This attribute
420 is read-only.
421 * ntasks - total number of tasks assigned to this timer. This
422 attribute is r/w inside the start route, and r/o elsewhere.
423 * tasks - number of tasks assigned to this worker. This attribute is
424 r/w inside the start route, and r/o elsewhere.
425 * nslices - number of slices this timer will slice tasks into. This
426 attribute is r/w inside the start route, and r/o elsewhere.
427 * slice - current slice this worker is processing. This attribute is
428 r/w inside the start route, and r/o elsewhere.
429
430 5. RPC Commands
431
432 5.1. ptimer.list
433 5.2. ptimer.pause
434 5.3. ptimer.continue
435 5.4. ptimer.start
436 5.5. ptimer.loop
437 5.6. ptimer.end
438
439 5.1. ptimer.list
440
441 List the loaded timers and their current state.
442
443 5.2. ptimer.pause
444
445 Pause execution of timer worker(s).
446
447 5.3. ptimer.continue
448
449 Continue execution of timer worker(s).
450
451 5.4. ptimer.start
452
453 Jump execution of timer worker(s) to the start route. This will
454 inherently continue execution if the worker was paused.
455
456 5.5. ptimer.loop
457
458 Jump execution of timer worker(s) to the loop route. This will
459 inherently continue execution if the worker was paused.
460
461 5.6. ptimer.end
462
463 Jump execution of timer worker(s) to the end route. This will
464 inherently continue execution if the worker was paused.
465
466 6. Example Usages
467
468 6.1. Call Rate Shaping
469
470 6.1.1. Global Traffic Shaping
471 6.1.2. Per Customer Traffic Shaping
472
473 6.2. Adaptive Routing
474 6.3. Dynamic Timers
475
476 6.3.1. Queue Control
477 6.3.2. Hot-Reload Tasks
478
479 6.1. Call Rate Shaping
480
481 These examples use the ptimer module to limit a customer's CPS (calls
482 per second), while smoothing out CPS spikes from the customer's SIP
483 server. "Call rate shaping" and "traffic shaping" will be used
484 interchangeably in this section.
485
486 Traffic shaping can be useful in cases where a customer has temporary
487 CPS spikes, or the customer has an under-performing queueing solution
488 they can not change. This is most apparent when the rate limiting
489 solution your upstream provider uses does not average CPS (common from
490 my experience, typically 1s sliding window). Short bursts in CPS from
491 one of your customers will therefore be blocked, and could even block
492 your other customers calls from being delivered.
493
494 The solution to short CPS bursts is queueing your customers calls, and
495 throttling call delivery within the CPS limit allocated to you by your
496 upstream provider. When a CPS spike occurs, calls that went over the
497 limit will stay in the queue until the next iteration, and relayed to
498 your upstream, spaced in time to stay within the limit. If a CPS burst
499 lasts for an extended period of time, calls continue to enqueue and
500 continue to process at the rate limit, until stale calls in the queue
501 hit the transaction timeout, typically configured via fr_timer modparam
502 in the tm module. You can tune the timeout of queued calls by changing
503 transaction timeouts.
504
505 The hard part with call rate shaping is timing precisely when requests
506 from the queue are processed, in order to stay within the CPS limit,
507 and spread out network congestion. Hence, ptimer is a good fit to time
508 the call queue processing (or any time sensitive tasks).
509
510 6.1.1. Global Traffic Shaping
511
512 In this example we want to set a global rate limit of 1000 CPS, and
513 throttle short CPS bursts so our customers get a higher delivery rate.
514
515 We will split the tasks in the queue such that our timer processes 10%
516 of the queue across 8 workers, every 100ms (1/10 the measurement
517 period). Resulting in calls from the queue being smoothed out over that
518 1sec, and staying within our constraint of 1K CPS at any point in time.
519
520 Example Implementation:
521 ...
522
523 loadmodule "mqueue.so"
524 loadmodule "ptimer.so"
525
526 ...
527
528 # global call queue
529 modparam("mqueue", "mqueue", "name=call_queue")
530 # synced slice timer
531 # each worker processes 12-13 calls every 100ms (during max load)
532 modparam("ptimer", "timer", "name=queue_timer;type=3;interval=100ms;nworkers=8;n
533 tasks=1000;nslices=80")
534 modparam("ptimer", "start", "timer=queue_timer;route=QUEUE_START")
535 modparam("ptimer", "loop", "timer=queue_timer;route=QUEUE_LOOP")
536
537 ...
538
539 request_route {
540 ...
541
542 # routing choices / message changes here
543
544 route(QUEUE_CALL);
545 }
546
547 route[QUEUE_CALL] {
548 if(t_suspend()) {
549 xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\
550 n");
551 mq_add("call_queue", "T(id_index)", "$T(id_label)");
552 exit;
553 }
554
555 xlog("L_ERR", "failed queuing call $ci\n");
556 sl_reply_error();
557 exit;
558 }
559
560 route[RELAY] {
561 ...
562
563 if(!t_relay()) {
564 send_reply_error();
565 }
566 }
567
568 route[QUEUE_START] {
569 # start each worker on a different slice
570 $ptimer(slice) = $ptimer(worker) * 10;
571 }
572
573 route[QUEUE_LOOP] {
574 $var(i) = 0;
575 while($var(i) < $ptimer(tasks)) {
576 if(mq_fetch("call_queue")) {
577 if(!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "RELAY")) {
578 xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)]
579 \n");
580 }
581 }
582 $var(i) = $var(i) + 1;
583 }
584 }
585
586 ...
587
588 6.1.2. Per Customer Traffic Shaping
589
590 In this example we want to set a different rate limit for each of our
591 customers. Customer 0-2 we sold 8,20,50 CPS respectively. Again, we
592 will throttle short CPS bursts so our customers get a higher delivery
593 rate.
594
595 To achieve this we will allocate each customer a queue and worker of
596 their own. Similar to the global example, we will split the queue tasks
597 into 10% chunks to evenlu distribute within each second (100ms
598 interval).
599
600 Example Implementation:
601 ...
602
603 loadmodule "mqueue.so"
604 loadmodule "ptimer.so"
605
606 ...
607
608 # customer call queues
609 # we could alternative have another data source to look up this queue in start r
610 oute
611 modparam("mqueue", "mqueue", "name=customer_0")
612 modparam("mqueue", "mqueue", "name=customer_1")
613 modparam("mqueue", "mqueue", "name=customer_2")
614 # synced slice timers for each customer
615 # we could allocate more workers per customer if needed
616 # if we wanted to lookup the quueue with a different identifier
617 # we would also define a start route here
618 modparam("ptimer", "timer", "name=customer_0;type=3;interval=100ms;nworkers=1;nt
619 asks=8;nslices=10")
620 modparam("ptimer", "loop", "timer=customer_0;route=QUEUE_LOOP")
621 modparam("ptimer", "timer", "name=customer_1;type=3;interval=100ms;nworkers=1;nt
622 asks=8;nslices=10")
623 modparam("ptimer", "loop", "timer=customer_1;route=QUEUE_LOOP")
624 modparam("ptimer", "timer", "name=customer_2;type=3;interval=100ms;nworkers=1;nt
625 asks=8;nslices=10")
626 modparam("ptimer", "loop", "timer=customer_2;route=QUEUE_LOOP")
627
628 ...
629
630 request_route {
631 ...
632
633 # routing choices / message changes here
634
635 route(QUEUE_CALL);
636 }
637
638 route[QUEUE_CALL] {
639 if(t_suspend()) {
640 xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\
641 n");
642 mq_add("call_queue", "T(id_index)", "$T(id_label)");
643 exit;
644 }
645
646 xlog("L_ERR", "failed queuing call $ci\n");
647 sl_reply_error();
648 exit;
649 }
650
651 route[RELAY] {
652 ...
653
654 if(!t_relay()) {
655 send_reply_error();
656 }
657 }
658
659 route[QUEUE_LOOP] {
660 $var(i) = 0;
661 while($var(i) < $ptimer(tasks)) {
662 if(mq_fetch("$ptimer(name)")) {
663 if(!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "RELAY")) {
664 xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)]
665 \n");
666 }
667 }
668 $var(i) = $var(i) + 1;
669 }
670 }
671
672 ...
673
674 6.2. Adaptive Routing
675
676 In this example we demonstrate how ptimer can be used to dynamically
677 update destinations in a route set based on admin defined metrics. The
678 end goal is to guarantee we are providing the level of service we
679 promised the customer.
680
681 We will use the following metrics (they could be anything you want):
682 * MOS - Mean Opinion Score
683 * CCR - Call Completion Ratio
684 * NER - Network Effectiveness Ratio
685
686 For brevity, assume updating the metrics is done elsewhere.
687
688 Example Implementation:
689 ...
690
691 loadmodule "dispatcher.so"
692 loadmodule "htable.so"
693 loadmodule "ptimer.so"
694
695 ...
696
697 # how we will grab the dst info
698 modparam("dispatcher", "flags", 2)
699 modparam("dispatcher", "xavp_dst", "ds_dst")
700 modparam("dispatcher", "xavp_ctx", "ds_ctx")
701 # where the metrics are stored (could be anywhere w/ fast access)
702 # key format: setid-uri-metric
703 modparam("htable", "htable", "dst_kpi=>size=8")
704 # where the customer SLA are stored (what we promised the customer)
705 modparam("htable", "htable", "min_kpi=>size=8")
706 # basic timer, each worker is handling one destination set (setid 0-2)
707 # we use the timer worker number to associate the dst set (0-2)
708 # that association could be mapped elsewhere and looked up in start route
709 modparam("ptimer", "timer", "name=route_optimizer;type=0;interval=500ms;nworkers
710 =3")
711 modparam("ptimer", "start", "timer=route_optimizer;route=OPTIMIZE_ROUTES_START")
712 modparam("ptimer", "loop", "timer=route_optimizer;route=OPTIMIZE_ROUTES_LOOP")
713
714 ...
715
716 route[OPTIMIZE_ROUTES_START] {
717 # grab the metric minimums when starting timer
718 $var(min_mos) = (int)$sht(min_kpi=>mos);
719 $var(min_ccr) = (int)$sht(min_kpi=>ccr);
720 $var(min_ner) = (int)$sht(min_kpi=>ner);
721 # sanity check
722 if(!ds_list_exists("$ptimer(worker)")) {
723 return -1;
724 }
725 # store all the destinations prior to modifying their state
726 # this is our local copy used in the loop route
727 ds_select("$ptimer(worker)", "8");
728 }
729
730 route[OPTIMIZE_ROUTES_LOOP] {
731 # remove / add from dst set based on metrics
732 $var(i) = 0;
733 while($var(i) < $xavp(ds_ctx=>cnt)) {
734 $var(prefix) = "$ptimer(worker)-$xavp(ds_dst[$var(i)]=>uri)";
735 if (
736 $sht(dst_kpi=>$var(prefix)-mos) < $var(min_mos) ||
737 $sht(dst_kpi=>$var(prefix)-ccr) < $var(min_ccr) ||
738 $sht(dst_kpi=>$var(prefix)-ner) < $var(min_ner)
739 ) {
740 ds_mark_addr("i", "$ptimer(worker)", "$xavp(ds_dst[$var(i)]=>uri)");
741 } else {
742 ds_mark_addr("a", "$ptimer(worker)", "$xavp(ds_dst[$var(i)]=>uri)");
743 }
744 $var(i) = $var(i) + 1;
745 }
746 }
747
748 ...
749
750 6.3. Dynamic Timers
751
752 These examples use the execution jumping features of ptimer to handle
753 common management use cases.
754
755 6.3.1. Queue Control
756
757 In this example we demonstrate how we can hot-swap the worker
758 processing a queue. This could be used to change routing to an IVR
759 during holiday, pause during maintenance, to revert new routing logic.
760
761 Example Implementation:
762 ...
763
764 loadmodule "mqueue.so"
765 loadmodule "ptimer.so"
766
767 ...
768
769 # call queue
770 modparam("mqueue", "mqueue", "name=call_queue")
771 # basic timer handling normal business hours
772 modparam("ptimer", "timer", "name=normal_timer;type=1;interval=100ms")
773 modparam("ptimer", "loop", "timer=normal_timer;route=NORMAL_QUEUE_START")
774 modparam("ptimer", "loop", "timer=normal_timer;route=HANDLE_QUEUE")
775 # basic timer handling holiday / after hours
776 modparam("ptimer", "timer", "name=holiday_timer;type=1;interval=100ms")
777 modparam("ptimer", "loop", "timer=holiday_timer;route=HOLIDAY_QUEUE_START")
778 modparam("ptimer", "loop", "timer=holiday_timer;route=HANDLE_QUEUE")
779
780 ...
781
782 request_route {
783 ...
784
785 route(QUEUE_CALL);
786 }
787
788 route[QUEUE_CALL] {
789 if(t_suspend()) {
790 xlog("L_INFO", "queued call for transaction [$T(id_index):$T(id_label)]\
791 n");
792 mq_add("call_queue", "T(id_index)", "$T(id_label)");
793 exit;
794 }
795
796 xlog("L_ERR", "failed queuing call $ci\n");
797 sl_reply_error();
798 exit;
799 }
800
801 route[RELAY_PSTN] {
802 $du = "sip:1.1.1.1:5060";
803
804 if(!t_relay()) {
805 send_reply_error();
806 }
807 }
808
809 route[RELAY_IVR] {
810 $du = "sip:9.9.9.9:5060";
811
812 if(!t_relay()) {
813 send_reply_error();
814 }
815 }
816
817 route[NORMAL_QUEUE_START] {
818 $var(relay) = "RELAY_PSTN";
819 }
820
821 route[HOLIDAY_QUEUE_START] {
822 $var(relay) = "RELAY_IVR";
823 # by default do not loop
824 return -1;
825 }
826
827 route[HANDLE_QUEUE] {
828 $var(c) = mq_size("$ptimer(name)");
829 $var(i) = 0;
830 while($var(i) < $var(c)) {
831 if (mq_fetch("call_queue")) {
832 if (!t_continue("$mqk(call_queue)", "$mqv(call_queue)", "$var(relay)
833 ")) {
834 xlog("L_ERR", "failed resuming transaction [$mqk(myq):$mqv(myq)]
835 \n");
836 }
837 }
838 $var(i) = $var(i) + 1;
839 }
840 }
841
842 ...
843
844 External Program:
845 # holiday starts
846 kamcmd ptimer.pause normal_timer
847 kamcmd ptimer.continue holiday_timer
848
849 # holiday ends
850 kamcmd ptimer.pause holiday_timer
851 kamcmd ptimer.continue normal_timer
852
853 6.3.2. Hot-Reload Tasks
854
855 In this example we demonstrate how we can load new data for the timer
856 to process without reloading. This flexibility means we can load new
857 tasks from any data source directly into the background worker process.
858
859 Example Implementation:
860 ...
861
862 loadmodule "http_client.so"
863 loadmodule "jansson.so"
864 loadmodule "ptimer.so"
865
866 ...
867
868 # synced slice timer that pulls data from an HTTP API
869 modparam("ptimer", "timer", "name=t1;type=3;interval=100ms;nslices=10")
870 modparam("ptimer", "loop", "timer=t1;route=GET_DATA")
871 modparam("ptimer", "loop", "timer=t1;route=HANDLE_DATA")
872
873 ...
874
875 route[GET_DATA] {
876 # data pulled for this example: {"data":[{"a":100},{"a":200}], "len", 2}
877 http_client_get("http://api.example.com/data", "$var(res)");
878 # "ntasks" will be sliced by the timer into "tasks" available in loop
879 jansson_get("len", "$var(res)", "$ptimer(ntasks)");
880 jansson_get("data", "$var(res)", "$var(data)");
881 jansson_xdecode("$var(data)", "worker_data");
882 }
883
884 route[HANDLE_DATA] {
885 $var(i) = 0;
886 while($var(i) < $ptimer(tasks)) {
887 # do something with the data
888 xlog("L_INFO", "a = $xavp(worker_data[$var(i)]=>a)\n");
889 $var(i) = $var(i) + 1;
890 }
891 }
892
893 ...
894
895 Another Program:
896 # could be within xhttp (as postback) or some other program
897 # when the data is updated we jump the timer back to start route
898 kamcmd ptimer.start t1