(closes issue #13557)
[asterisk/asterisk.git] / doc / CODING-GUIDELINES
1             --------------------------------------
2             == Asterisk Coding Guidelines ==
3             --------------------------------------
4
5 This document gives some basic indication on how the asterisk code
6 is structured. The first part covers the structure and style of
7 individual files. The second part (TO BE COMPLETED) covers the
8 overall code structure and the build architecture.
9
10 Please read it to the end to understand in detail how the asterisk
11 code is organized, and to know how to extend asterisk or contribute
12 new code.
13
14 We are looking forward to your contributions to Asterisk - the 
15 Open Source PBX! As Asterisk is a large and in some parts very
16 time-sensitive application, the code base needs to conform to
17 a common set of coding rules so that many developers can enhance
18 and maintain the code. Code also needs to be reviewed and tested
19 so that it works and follows the general architecture and guide-
20 lines, and is well documented.
21
22 Asterisk is published under a dual-licensing scheme by Digium.
23 To be accepted into the codebase, all non-trivial changes must be
24 licensed to Digium. For more information, see the electronic license
25 agreement on http://bugs.digium.com/.
26
27 Patches should be in the form of a unified (-u) diff, made from a checkout
28 from subversion.
29
30 /usr/src/asterisk$ svn diff > mypatch
31
32 If you would like to only include changes to certain files in the patch, you
33 can list them in the "svn diff" command:
34
35 /usr/src/asterisk$ svn diff somefile.c someotherfile.c > mypatch
36
37                 -----------------------------------
38                 ==  PART ONE: CODING GUIDELINES  ==
39                 -----------------------------------
40
41 * General rules
42 ---------------
43
44 - All code, filenames, function names and comments must be in ENGLISH.
45
46 - Don't annotate your changes with comments like "/* JMG 4/20/04 */";
47   Comments should explain what the code does, not when something was changed
48   or who changed it. If you have done a larger contribution, make sure
49   that you are added to the CREDITS file.
50
51 - Don't make unnecessary whitespace changes throughout the code.
52   If you make changes, submit them to the tracker as separate patches
53   that only include whitespace and formatting changes.
54
55 - Don't use C++ type (//) comments.
56
57 - Try to match the existing formatting of the file you are working on.
58
59 - Use spaces instead of tabs when aligning in-line comments or #defines (this makes 
60   your comments aligned even if the code is viewed with another tabsize)
61
62 * File structure and header inclusion
63 -------------------------------------
64
65 Every C source file should start with a proper copyright
66 and a brief description of the content of the file.
67 Following that, you should immediately put the following lines:
68
69 #include "asterisk.h"
70 ASTERISK_FILE_VERSION(__FILE__, "$Revision$")
71
72 "asterisk.h" resolves OS and compiler dependencies for the basic
73 set of unix functions (data types, system calls, basic I/O
74 libraries) and the basic Asterisk APIs.
75 ASTERISK_FILE_VERSION() stores in the executable information
76 about the file.   
77
78 Next, you should #include extra headers according to the functionality
79 that your file uses or implements. For each group of functions that
80 you use there is a common header, which covers OS header dependencies
81 and defines the 'external' API of those functions (the equivalent
82 of 'public' members of a class).  As an example:
83
84     asterisk/module.h
85         if you are implementing a module, this should be included in one
86         of the files that are linked with the module.
87
88     asterisk/io.h
89         access to extra file I/O functions (stat, fstat, playing with
90         directories etc)
91
92     asterisk/network.h
93         basic network I/O - all of the socket library, select/poll,
94         and asterisk-specific (usually either thread-safe or reentrant
95         or both) functions to play with socket addresses.
96
97     asterisk/app.h
98         parsing of application arguments
99
100     asterisk/channel.h
101         struct ast_channel and functions to manipulate it
102
103 For more information look at the headers in include/asterisk/ .
104 These files are usually self-sufficient, i.e. they recursively #include
105 all the extra headers they need.
106
107 The equivalent of 'private' members of a class are either directly in
108 the C source file, or in files named asterisk/mod_*.h to make it clear
109 that they are not for inclusion by generic code.
110
111 Keep the number of header files small by not including them unnecessarily.
112 Don't cut&paste list of header files from other sources, but only include
113 those you really need. Apart from obvious cases (e.g. module.h which
114 is almost always necessary) write a short comment next to each #include to
115 explain why you need it.
116
117
118 * Declaration of functions and variables
119 ----------------------------------------
120
121 - Do not declare variables mid-block (e.g. like recent GNU compilers support)
122   since it is harder to read and not portable to GCC 2.95 and others.
123
124 - Functions and variables that are not intended to be used outside the module
125   must be declared static.
126
127 - When reading integer numeric input with scanf (or variants), do _NOT_ use '%i'
128   unless you specifically want to allow non-base-10 input; '%d' is always a better
129   choice, since it will not silently turn numbers with leading zeros into base-8.
130
131 - Strings that are coming from input should not be used as a first argument to
132   a formatted *printf function.
133
134 * Use the internal API
135 ----------------------
136
137 - Make sure you are aware of the string and data handling functions that exist
138   within Asterisk to enhance portability and in some cases to produce more
139   secure and thread-safe code. Check utils.c/utils.h for these.
140
141 - If you need to create a detached thread, use the ast_pthread_create_detached()
142   normally or ast_pthread_create_detached_background() for a thread with a smaller
143   stack size.  This reduces the replication of the code to handle the pthread_attr_t
144   structure.
145
146 * Code formatting
147 -----------------
148
149 Roughly, Asterisk code formatting guidelines are generally equivalent to the 
150 following:
151
152 # indent -i4 -ts4 -br -brs -cdw -lp -ce -nbfda -npcs -nprs -npsl -nbbo -saf -sai -saw -cs -l90 foo.c
153
154 this means in verbose:
155  -i4:    indent level 4
156  -ts4:   tab size 4
157  -br:    braces on if line
158  -brs:   braces on struct decl line
159  -cdw:   cuddle do while
160  -lp:    line up continuation below parenthesis
161  -ce:    cuddle else
162  -nbfda: dont break function decl args
163  -npcs:  no space after function call names
164  -nprs:  no space after parentheses
165  -npsl:  dont break procedure type
166  -saf:   space after for
167  -sai:   space after if
168  -saw:   space after while
169  -cs:    space after cast
170  -ln90:  line length 90 columns
171
172 Function calls and arguments should be spaced in a consistent way across
173 the codebase.
174         GOOD: foo(arg1, arg2);
175         BAD: foo(arg1,arg2);
176         BAD: foo (arg1, arg2);
177         BAD: foo( arg1, arg2 );
178         BAD: foo(arg1, arg2,arg3);
179
180 Don't treat keywords (if, while, do, return) as if they were functions;
181 leave space between the keyword and the expression used (if any). For 'return',
182 don't even put parentheses around the expression, since they are not
183 required.
184
185 There is no shortage of whitespace characters :-) Use them when they make
186 the code easier to read. For example:
187
188         for (str=foo;str;str=str->next)
189
190 is harder to read than
191
192         for (str = foo; str; str = str->next)
193
194 Following are examples of how code should be formatted.
195
196 - Functions:
197 int foo(int a, char *s)
198 {
199         return 0;
200 }
201
202 - If statements:
203 if (foo) {
204         bar();
205 } else {
206         blah();
207 }
208
209 - Case statements:
210 switch (foo) {
211 case BAR:
212         blah();
213         break;
214 case OTHER:
215         other();
216         break;
217 }
218
219 - No nested statements without braces, e.g.:
220
221 for (x = 0; x < 5; x++)
222         if (foo) 
223                 if (bar)
224                         baz();
225
226 instead do:
227 for (x = 0; x < 5; x++) {
228         if (foo) {
229                 if (bar) {
230                         baz();
231                 }
232         }
233 }
234
235 - Always use braces around the statements following an if/for/while construct,
236 even if not strictly necessary, as it reduces future possible problems.
237
238 - Don't build code like this:
239
240 if (foo) {
241         /* .... 50 lines of code ... */
242 } else {
243         result = 0;
244         return;
245 }
246
247 Instead, try to minimize the number of lines of code that need to be
248 indented, by only indenting the shortest case of the 'if'
249 statement, like so:
250
251 if (!foo) {
252         result = 0;
253         return;
254 }
255
256 .... 50 lines of code ....
257
258 When this technique is used properly, it makes functions much easier to read
259 and follow, especially those with more than one or two 'setup' operations
260 that must succeed for the rest of the function to be able to execute.
261
262 - Labels/goto are acceptable
263 Proper use of this technique may occasionally result in the need for a
264 label/goto combination so that error/failure conditions can exit the
265 function while still performing proper cleanup. This is not a bad thing!
266 Use of goto in this situation is encouraged, since it removes the need
267 for excess code indenting without requiring duplication of cleanup code.
268        
269 - Never use an uninitialized variable
270 Make sure you never use an uninitialized variable.  The compiler will 
271 usually warn you if you do so. However, do not go too far the other way,
272 and needlessly initialize variables that do not require it. If the first
273 time you use a variable in a function is to store a value there, then
274 initializing it at declaration is pointless, and will generate extra
275 object code and data in the resulting binary with no purpose. When in doubt,
276 trust the compiler to tell you when you need to initialize a variable;
277 if it does not warn you, initialization is not needed.
278
279 - Do not cast 'void *'
280 Do not explicitly cast 'void *' into any other type, nor should you cast any
281 other type into 'void *'. Implicit casts to/from 'void *' are explicitly
282 allowed by the C specification. This means the results of malloc(), calloc(),
283 alloca(), and similar functions do not _ever_ need to be cast to a specific
284 type, and when you are passing a pointer to (for example) a callback function
285 that accepts a 'void *' you do not need to cast into that type.
286
287 * Function naming
288 -----------------
289
290 All public functions (those not marked 'static'), must be named "ast_<something>"
291 and have a descriptive name.
292
293 As an example, suppose you wanted to take a local function "find_feature", defined
294 as static in a file, and used only in that file, and make it public, and use it
295 in other files. You will have to remove the "static" declaration and define a 
296 prototype in an appropriate header file (usually in include/asterisk). A more
297 specific name should be given, such as "ast_find_call_feature".
298
299 * Variable function argument parsing
300 ------------------------------------
301
302 Functions with a variable amount of arguments need a 'sentinel' when called.
303 Newer GNU C compilers are fine if you use NULL for this. Older versions (pre 4)
304 don't like this.
305 You should use the constant SENTINEL.
306 This one is defined in include/asterisk/compiler.h
307
308 * Variable naming
309 -----------------
310
311 - Global variables
312 Name global variables (or local variables when you have a lot of them or
313 are in a long function) something that will make sense to aliens who
314 find your code in 100 years.  All variable names should be in lower 
315 case, except when following external APIs or specifications that normally
316 use upper- or mixed-case variable names; in that situation, it is
317 preferable to follow the external API/specification for ease of
318 understanding.
319
320 Make some indication in the name of global variables which represent
321 options that they are in fact intended to be global.
322  e.g.: static char global_something[80]
323
324 - Don't use un-necessary typedef's
325 Don't use 'typedef' just to shorten the amount of typing; there is no substantial
326 benefit in this:
327 struct foo { int bar; }; typedef struct foo foo_t;
328
329 In fact, don't use 'variable type' suffixes at all; it's much preferable to
330 just type 'struct foo' rather than 'foo_s'.
331
332 - Use enums instead of #define where possible
333 Use enums rather than long lists of #define-d numeric constants when possible;
334 this allows structure members, local variables and function arguments to
335 be declared as using the enum's type. For example:
336
337 enum option {
338   OPT_FOO = 1,
339   OPT_BAR = 2,
340   OPT_BAZ = 4,
341 };
342
343 static enum option global_option;
344
345 static handle_option(const enum option opt)
346 {
347   ...
348 }
349
350 Note: The compiler will _not_ force you to pass an entry from the enum
351 as an argument to this function; this recommendation serves only to make
352 the code clearer and somewhat self-documenting. In addition, when using
353 switch/case blocks that switch on enum values, the compiler will warn
354 you if you forget to handle one or more of the enum values, which can be
355 handy.
356
357 * String handling
358 -----------------
359
360 Don't use strncpy for copying whole strings; it does not guarantee that the
361 output buffer will be null-terminated. Use ast_copy_string instead, which
362 is also slightly more efficient (and allows passing the actual buffer
363 size, which makes the code clearer).
364
365 Don't use ast_copy_string (or any length-limited copy function) for copying
366 fixed (known at compile time) strings into buffers, if the buffer is something
367 that has been allocated in the function doing the copying. In that case, you
368 know at the time you are writing the code whether the buffer is large enough
369 for the fixed string or not, and if it's not, your code won't work anyway!
370 Use strcpy() for this operation, or directly set the first two characters
371 of the buffer if you are just trying to store a one-character string in the
372 buffer. If you are trying to 'empty' the buffer, just store a single
373 NULL character ('\0') in the first byte of the buffer; nothing else is
374 needed, and any other method is wasteful.
375
376 In addition, if the previous operations in the function have already
377 determined that the buffer in use is adequately sized to hold the string
378 you wish to put into it (even if you did not allocate the buffer yourself),
379 use a direct strcpy(), as it can be inlined and optimized to simple
380 processor operations, unlike ast_copy_string().
381
382 * Use of functions
383 ------------------
384
385 For the sake of uclibc, do not use index, bcopy or bzero; use 
386 strchr(), memset(), and memmove() instead. uclibc can be configured
387 to supply these functions, but we can save these users
388 time and consternation if we abstain from using these
389 functions.
390
391 When making applications, always ast_strdupa(data) to a local pointer if
392 you intend to parse the incoming data string.
393
394         if (data)
395                 mydata = ast_strdupa(data);
396
397
398 - Use the argument parsing macros to declare arguments and parse them, i.e.:
399
400         AST_DECLARE_APP_ARGS(args,
401                 AST_APP_ARG(arg1);
402                 AST_APP_ARG(arg2);
403                 AST_APP_ARG(arg3);
404         );
405         parse = ast_strdupa(data);
406         AST_STANDARD_APP_ARGS(args, parse);
407
408 - Create generic code!
409 If you do the same or a similar operation more than one time, make it a
410 function or macro.
411
412 Make sure you are not duplicating any functionality already found in an
413 API call somewhere.  If you are duplicating functionality found in 
414 another static function, consider the value of creating a new API call 
415 which can be shared.
416
417 * Handling of pointers and allocations
418 --------------------------------------
419
420 - Dereference or localize pointers
421 Always dereference or localize pointers to things that are not yours like
422 channel members in a channel that is not associated with the current 
423 thread and for which you do not have a lock.
424         channame = ast_strdupa(otherchan->name);
425
426 - Use const on pointer arguments if possible
427 Use const on pointer arguments which your function will not be modifying, as this 
428 allows the compiler to make certain optimizations. In general, use 'const'
429 on any argument that you have no direct intention of modifying, as it can
430 catch logic/typing errors in your code when you use the argument variable
431 in a way that you did not intend.
432
433 - Do not create your own linked list code - reuse!
434 As a common example of this point, make an effort to use the lockable
435 linked-list macros found in include/asterisk/linkedlists.h. They are
436 efficient, easy to use and provide every operation that should be
437 necessary for managing a singly-linked list (if something is missing,
438 let us know!). Just because you see other open-coded list implementations
439 in the source tree is no reason to continue making new copies of
440 that code... There are also a number of common string manipulation
441 and timeval manipulation functions in asterisk/strings.h and asterisk/time.h;
442 use them when possible.
443
444 - Avoid needless allocations!
445 Avoid needless malloc(), strdup() calls. If you only need the value in
446 the scope of your function try ast_strdupa() or declare structs on the
447 stack and pass a pointer to them. However, be careful to _never_ call
448 alloca(), ast_strdupa() or similar functions in the argument list
449 of a function you are calling; this can cause very strange stack
450 arrangements and produce unexpected behavior.
451
452 -Allocations for structures
453 When allocating/zeroing memory for a structure, use code like this:
454
455 struct foo *tmp;
456
457 ...
458
459 tmp = ast_calloc(1, sizeof(*tmp));
460
461 Avoid the combination of ast_malloc() and memset().  Instead, always use
462 ast_calloc(). This will allocate and zero the memory in a single operation. 
463 In the case that uninitialized memory is acceptable, there should be a comment
464 in the code that states why this is the case.
465
466 Using sizeof(*tmp) instead of sizeof(struct foo) eliminates duplication of the 
467 'struct foo' identifier, which makes the code easier to read and also ensures 
468 that if it is copy-and-pasted it won't require as much editing.
469
470 The ast_* family of functions for memory allocation are functionally the same.
471 They just add an Asterisk log error message in the case that the allocation
472 fails for some reason. This eliminates the need to generate custom messages
473 throughout the code to log that this has occurred.
474
475 -String Duplications
476
477 The functions strdup and strndup can *not* accept a NULL argument. This results
478 in having code like this:
479
480         if (str)
481                 newstr = strdup(str);
482         else
483                 newstr = NULL;
484
485 However, the ast_strdup and ast_strdupa functions will happily accept a NULL
486 argument without generating an error.  The same code can be written as:
487         
488         newstr = ast_strdup(str);
489
490 Furthermore, it is unnecessary to have code that malloc/calloc's for the length
491 of a string (+1 for the terminating '\0') and then using strncpy to copy the
492 copy the string into the resulting buffer.  This is the exact same thing as
493 using ast_strdup.
494
495 * CLI Commands
496 --------------
497
498 New CLI commands should be named using the module's name, followed by a verb
499 and then any parameters that the command needs. For example:
500
501 *CLI> iax2 show peer <peername>
502
503 not
504
505 *CLI> show iax2 peer <peername>
506
507 * New dialplan applications/functions
508 -------------------------------------
509
510 There are two methods of adding functionality to the Asterisk
511 dialplan: applications and functions. Applications (found generally in
512 the apps/ directory) should be collections of code that interact with
513 a channel and/or user in some significant way. Functions (which can be
514 provided by any type of module) are used when the provided
515 functionality is simple... getting/retrieving a value, for
516 example. Functions should also be used when the operation is in no way
517 related to a channel (a computation or string operation, for example).
518
519 Applications are registered and invoked using the
520 ast_register_application function; see the apps/app_skel.c file for an
521 example.
522
523 Functions are registered using 'struct ast_custom_function'
524 structures and the ast_custom_function_register function.
525
526 * Doxygen API Documentation Guidelines
527 --------------------------------------
528
529 When writing Asterisk API documentation the following format should be
530 followed. Do not use the javadoc style.
531
532 /*!
533  * \brief Do interesting stuff.
534  *
535  * \param thing1 interesting parameter 1.
536  * \param thing2 interesting parameter 2.
537  *
538  * This function does some interesting stuff.
539  *
540  * \retval zero on success
541  * \retval -1 on error.
542  */
543 int ast_interesting_stuff(int thing1, int thing2)
544 {
545         return 0;
546 }
547
548 Notice the use of the \param, \brief, and \return constructs.  These should be
549 used to describe the corresponding pieces of the function being documented.
550 Also notice the blank line after the last \param directive.  All doxygen
551 comments must be in one /*! */ block.  If the function or struct does not need
552 an extended description it can be left out.
553
554 Please make sure to review the doxygen manual and make liberal use of the \a,
555 \code, \c, \b, \note, \li and \e modifiers as appropriate.
556
557 When documenting a 'static' function or an internal structure in a module,
558 use the \internal modifier to ensure that the resulting documentation
559 explicitly says 'for internal use only'.
560
561 Structures should be documented as follows.
562
563 /*!
564  * \brief A very interesting structure.
565  */
566 struct interesting_struct
567 {
568         /*! \brief A data member. */
569         int member1;
570
571         int member2; /*!< \brief Another data member. */
572 }
573
574 Note that /*! */ blocks document the construct immediately following them
575 unless they are written, /*!< */, in which case they document the construct
576 preceding them.
577
578 It is very much preferred that documentation is not done inline, as done in
579 the previous example for member2.  The first reason for this is that it tends
580 to encourage extremely brief, and often pointless, documentation since people
581 try to keep the comment from making the line extremely long.  However, if you
582 insist on using inline comments, please indent the documentation with spaces!
583 That way, all of the comments are properly aligned, regardless of what tab
584 size is being used for viewing the code.
585
586 * Finishing up before you submit your code
587 ------------------------------------------
588
589 - Look at the code once more
590 When you achieve your desired functionality, make another few refactor
591 passes over the code to optimize it.
592
593 - Read the patch
594 Before submitting a patch, *read* the actual patch file to be sure that 
595 all the changes you expect to be there are, and that there are no 
596 surprising changes you did not expect. During your development, that
597 part of Asterisk may have changed, so make sure you compare with the
598 latest CVS.
599
600 - Listen to advice
601 If you are asked to make changes to your patch, there is a good chance
602 the changes will introduce bugs, check it even more at this stage.
603 Also remember that the bug marshal or co-developer that adds comments 
604 is only human, they may be in error :-)
605
606 - Optimize, optimize, optimize
607 If you are going to reuse a computed value, save it in a variable
608 instead of recomputing it over and over.  This can prevent you from 
609 making a mistake in subsequent computations, making it easier to correct
610 if the formula has an error and may or may not help optimization but 
611 will at least help readability.
612
613 Just an example (so don't over analyze it, that'd be a shame):
614
615 const char *prefix = "pre";     
616 const char *postfix = "post";
617 char *newname;
618 char *name = "data";
619
620 if (name && (newname = alloca(strlen(name) + strlen(prefix) + strlen(postfix) + 3)))
621         snprintf(newname, strlen(name) + strlen(prefix) + strlen(postfix) + 3, "%s/%s/%s", prefix, name, postfix);
622
623 ...vs this alternative:
624
625 const char *prefix = "pre";
626 const char *postfix = "post";
627 char *newname;
628 char *name = "data";
629 int len = 0;
630
631 if (name && (len = strlen(name) + strlen(prefix) + strlen(postfix) + 3) && (newname = alloca(len)))
632         snprintf(newname, len, "%s/%s/%s", prefix, name, postfix);
633
634 * Creating new manager events?
635 ------------------------------
636 If you create new AMI events, please read manager.txt. Do not re-use
637 existing headers for new purposes, but please re-use existing headers
638 for the same type of data.
639
640 Manager events that signal a status are required to have one
641 event name, with a status header that shows the status.
642 The old style, with one event named "ThisEventOn" and another named
643 "ThisEventOff", is no longer approved.
644
645 Check manager.txt for more information on manager and existing
646 headers. Please update this file if you add new headers.
647
648 * Locking in Asterisk
649 -----------------------------
650
651 A) Locking Fundamentals
652
653 Asterisk is a heavily multithreaded application.  It makes extensive
654 use of locking to ensure safe access to shared resources between
655 different threads.
656
657 When more that one lock is involved in a given code path, there is the
658 potential for deadlocks.  A deadlock occurs when a thread is stuck
659 waiting for a resource that it will never acquire.  Here is a classic
660 example of a deadlock:
661
662    Thread 1                   Thread 2
663    ------------               ------------
664    Holds Lock A               Holds Lock B
665    Waiting for Lock B         Waiting for Lock A
666
667 In this case, there is a deadlock between threads 1 and 2.
668 This deadlock would have been avoided if both threads had
669 agreed that one must acquire Lock A before Lock B.
670
671 In general, the fundamental rule for dealing with multiple locks is
672
673     an order _must_ be established to acquire locks, and then all threads
674     must respect that order when acquiring locks.
675
676
677 A.1) Establishing a locking order
678
679 Because any ordering for acquiring locks is ok, one could establish
680 the rule arbitrarily, e.g. ordering by address, or by some other criterion.
681 The main issue, though, is defining an order that
682   i) is easy to check at runtime;
683   ii) reflects the order in which the code executes.
684 As an example, if a data structure B is only accessible through a
685 data structure A, and both require locking, then the natural order
686 is locking first A and then B.
687 As another example, if we have some unrelated data structures to
688 be locked in pairs, then a possible order can be based on the address
689 of the data structures themselves.
690
691 B) Minding the boundary between channel drivers and the Asterisk core
692
693 The #1 cause of deadlocks in Asterisk is by not properly following the
694 locking rules that exist at the boundary between Channel Drivers and
695 the Asterisk core.  The Asterisk core allocates an ast_channel, and
696 Channel Drivers allocate "technology specific private data" (PVT) that is
697 associated with an ast_channel.  Typically, both the ast_channel and
698 PVT have their own lock.  There are _many_
699 code paths that require both objects to be locked.
700
701 The locking order in this situation is the following:
702
703     1) ast_channel
704     2) PVT
705
706 Channel Drivers implement the ast_channel_tech interface to provide a
707 channel implementation for Asterisk.  Most of the channel_tech
708 interface callbacks are called with the associated ast_channel
709 locked.  When accessing technology specific data, the PVT can be locked
710 directly because the locking order is respected.
711
712 C) Preventing lock ordering reversals.
713
714 There are some code paths which make it extremely difficult to
715 respect the locking order.
716 Consider for example the following situation:
717
718     1) A message comes in over the "network"
719     2) The Channel Driver (CD) monitor thread receives the message
720     3) The CD associates the message with a PVT and locks the PVT
721     4) While processing the message, the CD must do something that requires
722        locking the ast_channel associated to the PVT
723
724 This is the point that must be handled carefully.
725 The following psuedo-code
726
727       unlock(pvt);
728       lock(ast_channel);
729       lock(pvt);
730
731 is _not_ correct for two reasons:
732
733 i) first and foremost, unlocking the PVT means that other threads
734    can acquire the lock and believe it is safe to modify the
735    associated data. When reacquiring the lock, the original thread
736    might find unexpected changes in the protected data structures.
737    This essentially means that the original thread must behave as if
738    the lock on the pvt was not held, in which case it could have
739    released it itself altogether;
740
741 ii) Asterisk uses the so called "recursive" locks, which allow a thread
742    to issue a lock() call multiple times on the same lock. Recursive
743    locks count the number of calls, and they require an equivalent
744    number of unlock() to be actually released.
745
746    For this reason, just calling unlock() once does not guarantee that the
747    lock is actually released -- it all depends on how many times lock()
748    was called before.
749
750 An alternative, but still incorrect, construct is widely used in
751 the asterisk code to try and improve the situation:
752
753       while (trylock(ast_channel) == FAILURE) {
754           unlock(pvt);
755           usleep(1); /* yield to other threads */
756           lock(pvt);
757       }
758
759 Here the trylock() is non blocking, so we do not deadlock if the ast_channel
760 is already locked by someone else: in this case, we try to unlock the PVT
761 (which happens only if the PVT lock counter is 1), yield the CPU to
762 give other threads a chance to run, and then acquire the lock again.
763
764 This code is not correct for two reasons:
765   i) same as in the previous example, it releases the lock when the thread
766      probably did not expect it;
767   ii) if the PVT lock counter is greater than 1 we will not
768      really release the lock on the PVT. We might be lucky and have the
769      other contender actually release the lock itself, and so we will "win"
770      the race, but if both contenders have their lock counts > 1 then
771      they will loop forever (basically replacing deadlock with livelock).
772
773 Another variant of this code is the following:
774
775     if (trylock(ast_channel) == FAILURE) {
776         unlock(pvt);
777         lock(ast_channel);
778         lock(pvt);
779     }
780
781 which has the same issues as the while(trylock...) code, but just
782 deadlocks instead of looping forever in case of lock counts > 1.
783
784 The deadlock/livelock could be in principle spared if one had an
785 unlock_all() function that calls unlock as many times as needed to
786 actually release the lock, and reports the count. Then we could do:
787
788     if (trylock(ast_channel) == FAILURE) {
789         n = unlock_all(pvt);
790         lock(ast_channel)
791         while (n-- > 0) lock(pvt);
792     }
793
794 The issue with unexpected unlocks remains, though.
795
796 C) Locking multiple channels.
797
798 The next situation to consider is what to do when you need a lock on
799 multiple ast_channels (or multiple unrelated data structures).
800
801 If we are sure that we do not hold any of these locks, then the
802 following construct is sufficient:
803
804          lock(MIN(chan1, chan2));
805          lock(MAX(chan1, chan2));
806
807 That type of code would follow an established locking order of always
808 locking the channel that has a lower address first.  Also keep in mind
809 that to use this construct for channel locking, one would have to go
810 through the entire codebase to ensure that when two channels are locked,
811 this locking order is used.
812    However, if we enter the above section of code with some lock held
813 (which would be incorrect using non-recursive locks, but is completely
814 legal using recursive mutexes) then the locking order is not guaranteed
815 anymore because it depends on which locks we already hold. So we have
816 to go through the same tricks used for the channel+PVT case.
817
818 D) Recommendations
819
820 As you can see from the above discussion, getting locking right is all
821 but easy. So please follow these recommendations when using locks:
822
823 *) Use locks only when really necessary
824     Please try to use locks only when strictly necessary, and only for
825     the minimum amount of time required to run critical sections of code.
826     A common use of locks in the current code is to protect a data structure
827     from being released while you use it.
828     With the use of reference-counted objects (astobj2) this should not be
829     necessary anymore.
830
831 *) Do not sleep while holding a lock
832     If possible, do not run any blocking code while holding a lock,
833     because you will also block other threads trying to access the same
834     lock. In many cases, you can hold a reference to the object to avoid
835     that it is deleted while you sleep, perhaps set a flag in the object
836     itself to report other threads that you have some pending work to
837     complete, then release and acquire the lock around the blocking path,
838     checking the status of the object after you acquire the lock to make
839     sure that you can still perform the operation you wanted to.
840
841 *) Try not to exploit the 'recursive' feature of locks.
842     Recursive locks are very convenient when coding, as you don't have to
843     worry, when entering a section of code, whether or not you already
844     hold the lock -- you can just protect the section with a lock/unlock
845     pair and let the lock counter track things for you.
846        But as you have seen, exploiting the features of recursive locks
847     make it a lot harder to implement proper deadlock avoidance strategies.
848     So please try to analyse your code and determine statically whether you
849     already hold a lock when entering a section of code.
850        If you need to call some function foo() with and without a lock held,
851     you could define two function as below:
852         foo_locked(...) {
853             ... do something, assume lock held
854         }
855
856         foo(...) {
857             lock(xyz)
858             ret = foo_locked(...)
859             unlock(xyz)
860             return ret;
861         }
862     and call them according to the needs.
863
864 *) Document locking rules.
865     Please document the locking order rules are documented for every
866     lock introduced into Asterisk.  This is done almost nowhere in the
867     existing code.  However, it will be expected to be there for newly
868     introduced code.  Over time, this information should be added for
869     all of the existing lock usage.
870
871 -----------------------------------------------------------------------
872
873
874             ------------------------------------
875             ==  PART TWO: BUILD ARCHITECTURE  ==
876             ------------------------------------
877
878 The asterisk build architecture relies on autoconf to detect the
879 system configuration, and on a locally developed tool (menuselect) to
880 select build options and modules list, and on gmake to do the build.
881
882 The first step, usually to be done soon after a checkout, is running
883 "./configure", which will store its findings in two files:
884
885     + include/asterisk/autoconfig.h
886         contains C macros, normally #define HAVE_FOO or HAVE_FOO_H ,
887         for all functions and headers that have been detected at build time.
888         These are meant to be used by C or C++ source files.
889
890     + makeopts
891         contains variables that can be used by Makefiles.
892         In addition to the usual CC, LD, ... variables pointing to
893         the various build tools, and prefix, includedir ... which are
894         useful for generic compiler flags, there are variables
895         for each package detected.
896         These are normally of the form FOO_INCLUDE=... FOO_LIB=...
897         FOO_DIR=... indicating, for each package, the useful libraries
898         and header files. 
899
900 The next step is to run "make menuselect", to extract the dependencies existing
901 between files and modules, and to store build options.
902 menuselect produces two files, both to be read by the Makefile:
903
904     + menuselect.makeopts
905         Contains for each subdirectory a list of modules that must be
906         excluded from the build, plus some additional informatiom.
907     + menuselect.makedeps
908         Contains, for each module, a list of packages it depends on.
909         For each of these packages, we can collect the relevant INCLUDE
910         and LIB files from makeopts. This file is based on information
911         in the .c source code files for each module.
912
913 The top level Makefile is in charge of setting up the build environment,
914 creating header files with build options, and recursively invoking the
915 subdir Makefiles to produce modules and the main executable.
916
917 The sources are split in multiple directories, more or less divided by
918 module type (apps/ channels/ funcs/ res/ ...) or by function, for the main
919 binary (main/ pbx/).
920
921
922 TO BE COMPLETED
923
924     
925 -----------------------------------------------
926 Welcome to the Asterisk development community!
927 Meet you on the asterisk-dev mailing list. 
928 Subscribe at http://lists.digium.com!
929
930 -- The Asterisk.org Development Team