Add documentation for timing modules used in Asterisk
[asterisk/asterisk.git] / doc / timing.txt
1 Asterisk Timing Interfaces
2 -------------------------------------
3 In the past, if internal timing were desired for an Asterisk system, then the 
4 only source acceptable was from DAHDI. Beginning with Asterisk 1.6.1, a new 
5 timing API was introduced which allows for various timing modules to be used. 
6 Included with Asterisk are the following timing modules:
7
8 res_timing_pthread.so
9 res_timing_dahdi.so
10 res_timing_timerfd.so (Beginning with Asterisk 1.6.2)
11
12 res_timing_pthread uses the POSIX pthreads library in order to provide timing. 
13 Since the code uses a commonly-implemented set of functions, res_timing_pthread 
14 is portable to many types of systems. In fact, this is the only timing source 
15 currently usable on a non-Linux system. Due to the fact that a single userspace 
16 thread is used to provide timing for all users of the timer, res_timing_pthread 
17 is also the least efficient of the timing sources and has been known to lose 
18 its effectiveness in a heavily-loaded environment. 
19
20 res_timing_dahdi uses timing mechanisms provided by DAHDI. This method of 
21 timing was previously the only means by which Asterisk could receive timing. It 
22 has the benefit of being efficient, and if a system is already going to use 
23 DAHDI hardware, then it makes good sense to use this timing source. If, 
24 however, there is no need for DAHDI other than as a timing source, this timing 
25 source may seem unattractive. For people who are upgrading from 1.4 and are used 
26 to the old ztdummy timing interface, res_timing_dahdi provides the interface 
27 to dahdi_dummy, which is ztdummy's replacement. 
28
29 res_timing_timerfd uses a timing mechanism provided directly by the Linux 
30 kernel. This timing interface is only available on Linux systems using a kernel 
31 version at least 2.6.25 and a glibc version at least 2.8. This interface has 
32 the benefit of being very efficient, but at the time this is being written, 
33 it is a relatively new feature on Linux, meaning that its availability is not 
34 widespread. 
35
36 What Asterisk does with the Timing Interfaces
37 ---------------------------------------------
38 By default, Asterisk will build and load all of the timing interfaces. These 
39 timing interfaces are "ordered" based on a hard-coded priority number defined 
40 in each of the modules. As of the time of this writing, the preferences for the 
41 modules is the following: res_timing_timerfd.so, res_timing_dahdi.so, 
42 res_timing_pthread.so. 
43
44 The only functionality that requires internal timing is IAX2 trunking. It may 
45 also be used when generating audio for playback, such as from a file. Even
46 though internal timing is not a requirement for most Asterisk functionality, 
47 it may be advantageous to use it since the alternative is to use timing based
48 on incoming frames of audio. If there are no incoming frames or if the incoming 
49 frames of audio are from an unreliable or jittery source, then the
50 corresponding outgoing audio will also be unreliable, or even worse, 
51 nonexistent. Using internal timing prevents such unreliability.
52
53 Customizations/Troubleshooting
54 ---------------------------------------------
55 Now that you know Asterisk's default preferences for timing modules, you may 
56 decide that you have a different preference. Maybe you're on a timerfd-capable 
57 system but you would prefer to get your timing from DAHDI since you already are 
58 using DAHDI to drive your hardware. 
59
60 Alternatively, you may have been directed to this document due to an error you 
61 are currently experiencing with Asterisk. If you receive an error message 
62 regarding timing not working correctly, then you can use one of the following 
63 suggestions to disable a faulty timing module. 
64
65 1. Don't build the timing modules you know you will not use. You can disable 
66 the compilation of any of the timing modules using menuselect. The modules are 
67 listed in the "Resource Modules" section. Note that if you have already built 
68 Asterisk and have received an error about a timing module not working properly, 
69 it is not sufficient to disable it from being built. You will need to remove 
70 the module from your modules directory (by default, /usr/lib/asterisk/modules)  
71 to make sure that it does not get loaded again. 
72
73 2. Build, but do not load the timing modules you know you will not use. You can 
74 edit modules.conf using "noload" lines to disable the loading of specific 
75 timing modules by default. Based on the note in the section above, you may 
76 realize that your Asterisk setup does not require internal timing at all. If 
77 this is the case, you can safely noload all timing modules. 
78
79 Important Notes
80 ----------------------------------------------
81 Some confusion has arisen regarding the fact that non-DAHDI timing interfaces 
82 are available now. One common misconception which has arisen is that since 
83 timing can be provided elsewhere, DAHDI is no longer required for using the 
84 MeetMe application. Unfortunately, this is not the case. In addition to 
85 providing timing, DAHDI also provides a conferencing engine which the MeetMe 
86 application requires. 
87
88 Starting with Asterisk 1.6.2, however, there will be a new application, 
89 ConfBridge, which will be capable of conference bridging without the use 
90 of DAHDI's built-in mixing engine.