diff --git a/contrib/asterisk-ng-doxygen b/contrib/asterisk-ng-doxygen index f13b42abb..42b8a99e9 100644 --- a/contrib/asterisk-ng-doxygen +++ b/contrib/asterisk-ng-doxygen @@ -25,7 +25,7 @@ DOXYFILE_ENCODING = UTF-8 # The PROJECT_NAME tag is a single word (or a sequence of words surrounded # by quotes) that should identify the project. -PROJECT_NAME = "Asterisk - the Open Source PBX" +PROJECT_NAME = "Asterisk - The Open Source Telephony Project" # The PROJECT_NUMBER tag can be used to enter a project or revision number. # This could be handy for archiving the generated documentation or diff --git a/include/asterisk/doxygen/architecture.h b/include/asterisk/doxygen/architecture.h new file mode 100644 index 000000000..27b8d2a5a --- /dev/null +++ b/include/asterisk/doxygen/architecture.h @@ -0,0 +1,716 @@ +/* + * Asterisk -- An open source telephony toolkit. + * + * Copyright (C) 2009, Digium, Inc. + * + * Russell Bryant + * + * See http://www.asterisk.org for more information about + * the Asterisk project. Please do not directly contact + * any of the maintainers of this project for assistance; + * the project provides a web site, mailing lists and IRC + * channels for your use. + * + * This program is free software, distributed under the terms of + * the GNU General Public License Version 2. See the LICENSE file + * at the top of the source tree. + */ + +/*! + * \file + * \author Russell Bryant + */ + +/*! +\page AsteriskArchitecture Asterisk Architecture Overview +\author Russell Bryant +\AsteriskTrunkWarning + +
+ +\section ArchTOC Table of Contents + + -# \ref ArchIntro + -# \ref ArchLayout + -# \ref ArchInterfaces + -# \ref ArchInterfaceCodec + -# \ref ArchInterfaceFormat + -# \ref ArchInterfaceAPIs + -# \ref ArchInterfaceAMI + -# \ref ArchInterfaceChannelDrivers + -# \ref ArchInterfaceBridge + -# \ref ArchInterfaceCDR + -# \ref ArchInterfaceCEL + -# \ref ArchInterfaceDialplanApps + -# \ref ArchInterfaceDialplanFuncs + -# \ref ArchInterfaceRTP + -# \ref ArchInterfaceTiming + -# \ref ArchThreadingModel + -# \ref ArchChannelThreads + -# \ref ArchMonitorThreads + -# \ref ArchServiceThreads + -# \ref ArchOtherThreads + -# \ref ArchConcepts + -# \ref ArchConceptBridging + -# \ref ArchCodeFlows + -# \ref ArchCodeFlowPlayback + -# \ref ArchCodeFlowBridge + -# \ref ArchDataStructures + -# \ref ArchAstobj2 + -# \ref ArchLinkedLists + -# \ref ArchDLinkedLists + -# \ref ArchHeap + -# \ref ArchDebugging + -# \ref ArchThreadDebugging + -# \ref ArchMemoryDebugging + +
+ +\section ArchIntro Introduction + +This section of the documentation includes an overview of the Asterisk architecture +from a developer's point of view. For detailed API discussion, see the documentation +associated with public API header files. This documentation assumes some knowledge +of what Asterisk is and how to use it. + +The intent behind this documentation is to start looking at Asterisk from a high +level and progressively dig deeper into the details. It begins with talking about +the different types of components that make up Asterisk and eventually will go +through interactions between these components in different use cases. + +Throughout this documentation, many links are also provided as references to more +detailed information on related APIs, as well as the related source code to what +is being discussed. + +Feedback and contributions to this documentation are very welcome. Please send your +comments to the asterisk-dev mailing list on http://lists.digium.com/. + +Thank you, and enjoy Asterisk! + + +\section ArchLayout Modular Architecture + +Asterisk is a highly modularized application. There is a core application that +is built from the source in the main/ directory. However, it is +not very useful by itself. + +There are many modules that are loaded at runtime. Asterisk modules have names that +give an indication as to what functionality they provide, but the name is not special +in any technical sense. When Asterisk loads a module, the module registers the +functionality that it provides with the Asterisk core. + + -# Asterisk starts + -# Asterisk loads modules + -# Modules say "Hey Asterisk! I am a module. I can provide functionality X, Y, + and Z. Let me know when you'd like to use my functionality!" + + +\section ArchInterfaces Abstract Interface types + +There are many types of interfaces that modules can implement and register their +implementations of with the Asterisk core. Any module is allowed to register as +many of these different interfaces as they would like. Generally, related +functionality is grouped into a single module. + +In this section, the types of interfaces are discussed. Later, there will +be discussions about how different components interact in various scenarios. + +\subsection ArchInterfaceCodec Codec Interpreter + +An implementation of the codec interpreter interface provides the ability to +convert between two codecs. Asterisk currently only has the ability to translate +between audio codecs. + +These modules have no knowledge about phone calls or anything else about why +they are being asked to convert audio. They just get audio samples as input +in their specified input format, and are expected to provide audio in the +specified output format. + +It is possible to have multiple paths to get from codec A to codec B once many +codec implementations are registered. After modules have been loaded, Asterisk +builds a translation table with measurements of the performance of each codec +translator so that it can always find the best path to get from A to B. + +Codec modules typically live in the codecs/ directory in the +source tree. + +For a list of codec interpreter implementations, see \ref codecs. + +For additional information on the codec interpreter API, see the interface +definition in include/asterisk/translate.h. + +For core implementation details related to the codec interpreter API, see +main/translate.c. + +\subsection ArchInterfaceFormat File Format Handler + +An implementation of the file format handler interface provides Asterisk the +ability to read and optionally write files. File format handlers may provide +access to audio, video, or image files. + +The interface for a file format handler is rather primitive. A module simply +tells the Asterisk core that it can handle files with a given %extension, +for example, ".wav". It also says that after reading the file, it will +provide audio in the form of codec X. If a file format handler provides the +ability to write out files, it also must specify what codec the audio should +be in before provided to the file format handler. + +File format modules typically live in the formats/ directory in the +source tree. + +For a list of file format handler implementations, see \ref formats. + +For additional information on the file format handler API, see the interface +definition in include/asterisk/file.h. + +For core implementation details related to the file format API, see +main/file.c. + +\subsection ArchInterfaceAPIs C API Providers + +There are some C APIs in Asterisk that are optional. Core APIs are built into +the main application and are always available. Optional C APIs are provided +by a module and are only available for use when the module is loaded. Some of +these API providers also contain their own interfaces that other modules can +implement and register. + +Modules that provide a C API typically live in the res/ directory +in the source tree. + +Some examples of modules that provide C APIs (potentially among other things) are: + - res_musiconhold.c + - res_calendar.c + - provides a calendar technology interface. + - res_odbc.c + - res_ael_share.c + - res_crypto.c + - res_curl.c + - res_jabber.c + - res_monitor.c + - res_smdi.c + - res_speech.c + - provides a speech recognition engine interface. + +\subsection ArchInterfaceAMI Manager Interface (AMI) Actions + +The Asterisk manager interface is a socket interface for monitoring and control +of Asterisk. It is a core feature built in to the main application. However, +modules can register %actions that may be requested by clients. + +Modules that register manager %actions typically do so as auxiliary functionality +to complement whatever main functionality it provides. For example, a module that +provides call conferencing services may have a manager action that will return the +list of participants in a conference. + +\subsection ArchInterfaceCLI CLI Commands + +The Asterisk CLI is a feature implemented in the main application. Modules may +register additional CLI commands. + +\subsection ArchInterfaceChannelDrivers Channel Drivers + +The Asterisk channel driver interface is the most complex and most important +interface available. The Asterisk channel API provides the telephony protocol +abstraction which allows all other Asterisk features to work independently of +the telephony protocol in use. + +The specific interface that channel drivers implement is the ast_channel_tech +interface. A channel driver must implement functions that perform various +call signaling tasks. For example, they must implement a method for initiating +a call and hanging up a call. The ast_channel data structure is the abstract +channel data structure. Each ast_channel instance has an associated +ast_channel_tech which identifies the channel type. An ast_channel instance +represents one leg of a call (a connection between Asterisk and an endpoint). + +Channel drivers typically live in the channels/ directory in the +source tree. + +For a list of channel driver implementations, see \ref channel_drivers. + +For additional information on the channel API, see +include/asterisk/channel.h. + +For additional implementation details regarding the core ast_channel API, see +main/channel.c. + +\subsection ArchInterfaceBridge Bridging Technologies + +Bridging is the operation which connects two or more channels together. A simple +two channel bridge is a normal A to B phone call, while a multi-party bridge would +be something like a 3-way call or a full conference call. + +The bridging API allows modules to register bridging technologies. An implementation +of a bridging technology knows how to take two (or optionally more) channels and +connect them together. Exactly how this happens is up to the implementation. + +This interface is used such that the code that needs to pass audio between channels +doesn't need to know how it is done. Underneath, the conferencing may be done in +the kernel (via DAHDI), via software methods inside of Asterisk, or could be done +in hardware in the future if someone implemented a module to do so. + +At the time of this writing, the bridging API is still relatively new, so it is +not used everywhere that bridging operations are performed. The ConfBridge dialplan +application is a new conferencing application which has been implemented on top of +this bridging API. + +Bridging technology modules typically live in the bridges/ directory +in the source tree. + +For a list of bridge technology implementations, see \ref bridges. + +For additional information on the bridging API, see +include/asterisk/bridging.h and +include/asterisk/bridging_technology.h. + +For additional implementation details regarding the core bridging API, see +main/bridging.c. + +\subsection ArchInterfaceCDR Call Detail Record (CDR) Handlers + +The Asterisk core implements functionality for keeping records of calls. These +records are built while calls are processed and live in data structures. At the +end of the call, these data structures are released. Before the records are thrown +away, they are passed in to all of the registered CDR handlers. These handlers may +write out the records to a file, post them to a database, etc. + +CDR modules typically live in the cdr directory in the source tree. + +For a list of CDR handlers, see \ref cdr_drivers. + +For additional information on the CDR API, see +include/asterisk/cdr.h. + +For additional implementation details regarding CDR handling, see +main/cdr.c. + +\subsection ArchInterfaceCEL Call Event Logging (CEL) Handlers + +The Asterisk core includes a generic event system that allows Asterisk components +to report events that can be subscribed to by other parts of the system. One of +the things built on this event system is Call Event Logging (CEL). + +CEL is similar to CDR in that they are both for tracking call history. While CDR +records are typically have a one record to one call relationship, CEL events are +many events to one call. The CEL modules look very similar to CDR modules. + +CEL modules typically live in the cel/ directory in the source tree. + +For a list of CEL handlers, see \ref cel_drivers. + +For additional information about the CEL API, see +include/asterisk/cel.h. + +For additional implementation details for the CEL API, see main/cel.c. + +\subsection ArchInterfaceDialplanApps Dialplan Applications + +Dialplan applications implement features that interact with calls that can be +executed from the Asterisk dialplan. For example, in extensions.conf: + +exten => 123,1,NoOp() + +In this case, NoOp is the application. Of course, NoOp doesn't actually do +anything. + +These applications use a %number of APIs available in Asterisk to interact with +the channel. One of the most important tasks of an application is to continuously +read audio from the channel, and also write audio back to the channel. The details +of how this is done is usually hidden behind an API call used to play a file or wait +for digits to be pressed by a caller. + +In addition to interacting with the channel that originally executed the application, +dialplan applications sometimes also create additional outbound channels. +For example, the Dial() application creates an outbound channel and bridges it to the +inbound channel. Further discussion about the functionality of applications will be +discussed in detailed use cases. + +Dialplan applications are typically found in the apps/ directory in +the source tree. + +For a list of dialplan applications, see \ref applications. + +For details on the API used to register an application with the Asterisk core, see +include/asterisk/pbx.h. + +\subsection ArchInterfaceDialplanFuncs Dialplan Functions + +As the name suggests, dialplan functions, like dialplan applications, are primarily +used from the Asterisk dialplan. Functions are used mostly in the same way that +variables are used in the dialplan. They provide a read and/or write interface, with +optional arguments. While they behave similarly to variables, they storage and +retrieval of a value is more complex than a simple variable with a text value. + +For example, the CHANNEL() dialplan function allows you to access +data on the current channel. + +exten => 123,1,NoOp(This channel has the name: ${CHANNEL(name)}) + +Dialplan functions are typically found in the funcs/ directory in +the source tree. + +For a list of dialplan function implementations, see \ref functions. + +For details on the API used to register a dialplan function with the Asterisk core, +see include/asterisk/pbx.h. + +\subsection ArchInterfaceRTP RTP Engines + +The Asterisk core provides an API for handling RTP streams. However, the actual +handling of these streams is done by modules that implement the RTP engine interface. +Implementations of an RTP engine typically live in the res/ directory +of the source tree, and have a res_rtp_ prefix in their name. + +\subsection ArchInterfaceTiming Timing Interfaces + +The Asterisk core implements an API that can be used by components that need access +to timing services. For example, a timer is used to send parts of an audio file at +proper intervals when playing back a %sound file to a caller. The API relies on +timing interface implementations to provide a source for reliable timing. + +Timing interface implementations are typically found in the res/ +subdirectory of the source tree. + +For a list of timing interface implementations, see \ref timing_interfaces. + +For additional information on the timing API, see include/asterisk/timing.h. + +For additional implementation details for the timing API, see main/timing.c. + + +\section ArchThreadingModel Asterisk Threading Model + +Asterisk is a very heavily multi threaded application. It uses the POSIX threads API +to manage threads and related services such as locking. Almost all of the Asterisk code +that interacts with pthreads does so by going through a set of wrappers used for +debugging and code reduction. + +Threads in Asterisk can be classified as one of the following types: + + - Channel threads (sometimes referred to as PBX threads) + - Network Monitor threads + - Service connection threads + - Other threads + +\subsection ArchChannelThreads Channel Threads + +A channel is a fundamental concept in Asterisk. Channels are either inbound +or outbound. An inbound channel is created when a call comes in to the Asterisk +system. These channels are the ones that execute the Asterisk dialplan. A thread +is created for every channel that executes the dialplan. These threads are referred +to as a channel thread. They are sometimes also referred to as a PBX thread, since +one of the primary tasks of the thread is to execute the Asterisk dialplan for an +inbound call. + +A channel thread starts out by only being responsible for a single Asterisk channel. +However, there are cases where a second channel may also live in a channel thread. +When an inbound channel executes an application such as Dial(), an +outbound channel is created and bridged to the inbound channel once it answers. + +Dialplan applications always execute in the context of a channel thread. Dialplan +functions \i almost always do, as well. However, it is possible to read and write +dialplan functions from an asynchronous interface such as the Asterisk CLI or the +manager interface (AMI). However, it is still always the channel thread that is +the owner of the ast_channel data structure. + +\subsection ArchMonitorThreads Network Monitor Threads + +Network monitor threads exist in almost every major channel driver in Asterisk. +They are responsible for monitoring whatever network they are connected to (whether +that is an IP network, the PSTN, etc.) and monitor for incoming calls or other types +of incoming %requests. They handle the initial connection setup steps such as +authentication and dialed %number validation. Finally, once the call setup has been +completed, the monitor threads will create an instance of an Asterisk channel +(ast_channel), and start a channel thread to handle the call for the rest of its +lifetime. + +\subsection ArchServiceThreads Service Connection Threads + +There are a %number of TCP based services that use threads, as well. Some examples +include SIP and the AMI. In these cases, threads are used to handle each TCP +connection. + +The Asterisk CLI also operates in a similar manner. However, instead of TCP, the +Asterisk CLI operates using connections to a UNIX %domain socket. + +\subsection ArchOtherThreads Other Threads + +There are other miscellaneous threads throughout the system that perform a specific task. +For example, the event API (include/asterisk/event.h) uses a thread internally +(main/event.c) to handle asychronous event dispatching. The devicestate API +(include/asterisk/devicestate.h) uses a thread internally (main/devicestate.c) +to asynchronously process device state changes. + + +\section ArchConcepts Other Architecture Concepts + +This section covers some other important Asterisk architecture concepts. + +\subsection ArchConceptBridging Channel Bridging + +As previously mentioned when discussing the bridging technology interface +(\ref ArchInterfaceBridge), bridging is the act of connecting one or more channel +together so that they may pass audio between each other. However, it was also +mentioned that most of the code in Asterisk that does bridging today does not use +this new bridging infrastructure. So, this section discusses the legacy bridging +functionality that is used by the Dial() and Queue() +applications. + +When one of these applications decides it would like to bridge two channels together, +it does so by executing the ast_channel_bridge() API call. From there, there are +two types of bridges that may occur. + + -# Generic Bridge: A generic bridge (ast_generic_bridge()) is a bridging + method that works regardless of what channel technologies are in use. It passes + all audio and signaling through the Asterisk abstract channel and frame interfaces + so that they can be communicated between channel drivers of any type. While this + is the most flexible, it is also the least efficient bridging method due to the + levels of abstraction necessary. + -# Native Bridge: Channel drivers have the option of implementing their own + bridging functionality. Specifically, this means to implement the bridge callback + in the ast_channel_tech structure. If two channels of the same type are bridged, + a native bridge method is available, and Asterisk does not have a reason to force + the call to stay in the core of Asterisk, then the native bridge function will be + invoked. This allows channel drivers to take advantage of the fact that the + channels are the same type to optimize bridge processing. In the case of a DAHDI + channel, this may mean that the channels are bridged natively on hardware. In the + case of SIP, this means that Asterisk can direct the audio to flow between the + endpoints and only require the signaling to continue to flow through Asterisk. + + +\section ArchCodeFlows Code Flow Examples + +Now that there has been discussion about the various components that make up Asterisk, +this section goes through examples to demonstrate how these components work together +to provide useful functionality. + +\subsection ArchCodeFlowPlayback SIP Call to File Playback + +This example consists of a call that comes in to Asterisk via the SIP protocol. +Asterisk accepts this call, plays back a %sound file to the caller, and then hangs up. + +Example dialplan: + +exten => 5551212,1,Answer()
+exten => 5551212,n,Playback(demo-congrats)
+exten => 5551212,n,Hangup()
+ + -# Call Setup: An incoming SIP INVITE begins this scenario. It is received by + the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip + is responsible for handling this incoming request. Further, the monitor thread + is responsible for completing any handshake necessary to complete the call setup + process. + -# Accept Call: Once the SIP channel driver has completed the call setup process, + it accepts the call and initiates the call handling process in Asterisk. To do so, + it must allocate an instance of an abstract channel (ast_channel) using the + ast_channel_alloc() API call. This instance of an ast_channel will be referred to + as a SIP channel. The SIP channel driver will take care of SIP specific channel + initialization. Once the channel has been created and initialized, a channel thread + is created to handle the call (ast_pbx_start()). + -# Run the Dialplan:: The main loop that runs in the channel thread is the code + responsible for looking for the proper extension and then executing it. This loop + lives in ast_pbx_run() in main/pbx.c. + -# Answer the Call:: Once the dialplan is being executed, the first application + that is executed is Answer(). This application is a built in + application that is defined in main/pbx.c. The Answer() application + code simply executes the ast_answer() API call. This API call operates on an + ast_channel. It handles generic ast_channel hangup processing, as well as executes + the answer callback function defined in the associated ast_channel_tech for the + active channel. In this case, the sip_answer() function in chan_sip.c will get + executed to handle the SIP specific operations required to answer a call. + -# Play the File: The next step of the dialplan says to play back a %sound file + to the caller. The Playback() application will be executed. + The code for this application is in apps/app_playback.c. The code in the application + is pretty simple. It does argument handling and uses API calls to play back the + file, ast_streamfile(), ast_waitstream(), and ast_stopstream(), which set up file + playback, wait for the file to finish playing, and then free up resources. Some + of the important operations of these API calls are described in steps here: + -# Open a File: The file format API is responsible for opening the %sound file. + It will start by looking for a file that is encoded in the same format that the + channel is expecting to receive audio in. If that is not possible, it will find + another type of file that can be translated into the codec that the channel is + expecting. Once a file is found, the appropriate file format interface is invoked + to handle reading the file and turning it into internal Asterisk audio frames. + -# Set up Translation: If the encoding of the audio data in the file does not + match what the channel is expecting, the file API will use the codec translation + API to set up a translation path. The translate API will invoke the appropriate + codec translation interface(s) to get from the source to the destination format + in the most efficient way available. + -# Feed Audio to the Caller: The file API will invoke the timer API to know + how to send out audio frames from the file in proper intervals. At the same time, + Asterisk must also continuously service the incoming audio from the channel since + it will continue to arrive in real time. However, in this scenario, it will just + get thrown away. + -# Hang up the Call: Once the Playback() application has finished, + the dialplan execution loop continues to the next step in the dialplan, which is + Hangup(). This operates in a very similar manner to Answer() + in that it handles channel type agnostic hangup handling, and then calls down into + the SIP channel interface to handle SIP specific hangup processing. At this point, + even if there were more steps in the dialplan, processing would stop since the channel + has been hung up. The channel thread will exit the dialplan processing loop and + destroy the ast_channel data structure. + +\subsection ArchCodeFlowBridge SIP to IAX2 Bridged Call + +This example consists of a call that comes in to Asterisk via the SIP protocol. Asterisk +then makes an outbound call via the IAX2 protocol. When the far end over IAX2 answers, +the call is bridged. + +Example dialplan: + +exten => 5551212,n,Dial(IAX2/mypeer)
+ + -# Call Setup: An incoming SIP INVITE begins this scenario. It is received by + the SIP channel driver (chan_sip.c). Specifically, the monitor thread in chan_sip + is responsible for handling this incoming request. Further, the monitor thread + is responsible for completing any handshake necessary to complete the call setup + process. + -# Accept Call: Once the SIP channel driver has completed the call setup process, + it accepts the call and initiates the call handling process in Asterisk. To do so, + it must allocate an instance of an abstract channel (ast_channel) using the + ast_channel_alloc() API call. This instance of an ast_channel will be referred to + as a SIP channel. The SIP channel driver will take care of SIP specific channel + initialization. Once the channel has been created and initialized, a channel thread + is created to handle the call (ast_pbx_start()). + -# Run the Dialplan:: The main loop that runs in the channel thread is the code + responsible for looking for the proper extension and then executing it. This loop + lives in ast_pbx_run() in main/pbx.c. + -# Execute Dial(): The only step in this dialplan is to execute the + Dial() application. + -# Create an Outbound Channel: The Dial() application needs to + create an outbound ast_channel. It does this by first using the ast_request() + API call to request a channel called IAX2/mypeer. This API call + is a part of the core channel API (include/asterisk/channel.h). It will find + a channel driver of type IAX2 and then execute the request callback + in the appropriate ast_channel_tech interface. In this case, it is iax2_request() + in channels/chan_iax2.c. This asks the IAX2 channel driver to allocate an + ast_channel of type IAX2 and initialize it. The Dial() application + will then execute the ast_call() API call for this new ast_channel. This will + call into the call callback of the ast_channel_tech, iax2_call(), which requests + that the IAX2 channel driver initiate the outbound call. + -# Wait for Answer: At this point, the Dial() application waits for the + outbound channel to answer the call. While it does this, it must continue to + service the incoming audio on both the inbound and outbound channels. The loop + that does this is very similar to every other channel servicing loop in Asterisk. + The core features of a channel servicing loop include ast_waitfor() to wait for + frames on a channel, and then ast_read() on a channel once frames are available. + -# Handle Answer: Once the far end answers the call, the Dial() + application will communicate this back to the inbound SIP channel. It does this + by calling the ast_answer() core channel API call. + -# Make Channels Compatible: Before the two ends of the call can be connected, + Asterisk must make them compatible to talk to each other. Specifically, the two + channels may be sending and expecting to receive audio in a different format than + the other channel. The API call ast_channel_make_compatible() sets up translation + paths for each channel by instantiating codec translators as necessary. + -# Bridge the Channels: Now that both the inbound and outbound channels are + fully established, they can be connected together. This connection between the + two channels so that they can pass audio and signaling back and forth is referred + to as a bridge. The API call that handles the bridge is ast_channel_bridge(). + In this case, the main loop of the bridge is a generic bridge, ast_generic_bridge(), + which is the type of bridge that works regardless of the two channel types. A + generic bridge will almost always be used if the two channels are not of the same + type. The core functionality of a bridge loop is ast_waitfor() on both channels. + Then, when frames arrive on a channel, they are read using ast_read(). After reading + a frame, they are written to the other channel using ast_write(). + -# Breaking the Bridge: This bridge will continue until some event occurs that + causes the bridge to be broken, and control to be returned back down to the + Dial() application. For example, if one side of the call hangs up, + the bridge will stop. + -# Hanging Up:: After the bridge stops, control will return to the + Dial() application. The application owns the outbound channel since + that is where it was created. So, the outbound IAX2 channel will be destroyed + before Dial() is complete. Destroying the channel is done by using + the ast_hangup() API call. The application will return back to the dialplan + processing loop. From there, the loop will see that there is nothing else to + execute, so it will hangup on the inbound channel as well using the ast_hangup() + function. ast_hangup() performs a number of channel type independent hangup + tasks, but also executes the hangup callback of ast_channel_tech (sip_hangup()). + Finally, the channel thread exits. + + +\section ArchDataStructures Asterisk Data Structures + +Asterisk provides generic implementations of a number of data structures. + +\subsection ArchAstobj2 Astobj2 + +Astobj2 stands for the Asterisk Object model, version 2. The API is defined in +include/asterisk/astobj2.h. Some internal implementation details for astobj2 can +be found in main/astobj2.c. There is a version 1, and it still exists in the +source tree. However, it is considered deprecated. + +Astobj2 provides reference counted object handling. It also provides a container +interface for astobj2 objects. The container provided is a hash table. + +See the astobj2 API for more details about how to use it. Examples can be found +all over the code base. + +\subsection ArchLinkedLists Linked Lists + +Asterisk provides a set of macros for handling linked lists. They are defined in +include/asterisk/linkedlists.h. + +\subsection ArchDLinkedLists Doubly Linked Lists + +Asterisk provides a set of macros for handling doubly linked lists, as well. They +are defined in include/asterisk/dlinkedlists.h. + +\subsection ArchHeap Heap + +Asterisk provides an implementation of the max heap data structure. The API is defined +in include/asterisk/heap.h. The internal implementation details can be found in +main/heap.c. + + +\section ArchDebugging Asterisk Debugging Tools + +Asterisk includes a %number of built in debugging tools to help in diagnosing common +types of problems. + +\subsection ArchThreadDebugging Thread Debugging + +Asterisk keeps track of a list of all active threads on the system. A list of threads +can be viewed from the Asterisk CLI by running the command +core show threads. + +Asterisk has a compile time option called DEBUG_THREADS. When this is on, +the pthread wrapper API in Asterisk keeps track of additional information related to +threads and locks to aid in debugging. In addition to just keeping a list of threads, +Asterisk also maintains information about every lock that is currently held by any +thread on the system. It also knows when a thread is blocking while attempting to +acquire a lock. All of this information is extremely useful when debugging a deadlock. +This data can be acquired from the Asterisk CLI by running the +core show locks CLI command. + +The definitions of these wrappers can be found in include/asterisk/lock.h +and include/asterisk/utils.h. Most of the implementation details can be +found in main/utils.c. + +\subsection ArchMemoryDebugging Memory debugging + +Dynamic memory management in Asterisk is handled through a %number of wrappers defined +in include/asterisk/utils.h. By default, all of these wrappers use the +standard C library malloc(), free(), etc. functions. However, if Asterisk is compiled +with the MALLOC_DEBUG option enabled, additional memory debugging is included. + +The Asterisk memory debugging system provides the following features: + + - Track all current allocations including their size and the file, function, and line + %number where they were initiated. + - When releasing memory, do some basic fence checking to see if anything wrote into the + few bytes immediately surrounding an allocation. + - Get notified when attempting to free invalid memory. + +A %number of CLI commands are provided to access data on the current set of memory +allocations. Those are: + + - memory show summary + - memory show allocations + +The implementation of this memory debugging system can be found in +main/astmm.c. + + +
+Return to the \ref ArchTOC + */ + diff --git a/include/asterisk/doxyref.h b/include/asterisk/doxyref.h index 3cbe21a35..a9c0d190e 100644 --- a/include/asterisk/doxyref.h +++ b/include/asterisk/doxyref.h @@ -658,6 +658,11 @@ * \arg \ref codecs */ +/*! + * \addtogroup rtp_engines Module: RTP Engines + * \section rtp_engine_blah Asterisk RTP Engines + */ + /*! * \page AstHTTP AMI over HTTP support * The http.c file includes support for manager transactions over diff --git a/main/asterisk.c b/main/asterisk.c index a5a33d043..ea231d40e 100644 --- a/main/asterisk.c +++ b/main/asterisk.c @@ -19,7 +19,7 @@ /* Doxygenified Copyright Header */ /*! - * \mainpage Asterisk -- An Open Source Telephony Toolkit + * \mainpage Asterisk -- The Open Source Telephony Project * * \par Developer Documentation for Asterisk * @@ -30,6 +30,8 @@ * please see the appendices for information on coding guidelines, * release management, commit policies, and more. * + * \arg \ref AsteriskArchitecture + * * \par Additional documentation * \arg \ref Licensing * \arg \ref DevDoc diff --git a/res/res_rtp_asterisk.c b/res/res_rtp_asterisk.c index 2fde7a419..eba2e852f 100644 --- a/res/res_rtp_asterisk.c +++ b/res/res_rtp_asterisk.c @@ -24,6 +24,8 @@ * \author Mark Spencer * * \note RTP is defined in RFC 3550. + * + * \ingroup rtp_engines */ #include "asterisk.h" diff --git a/res/res_rtp_multicast.c b/res/res_rtp_multicast.c index 3752ebefc..a612db5e8 100644 --- a/res/res_rtp_multicast.c +++ b/res/res_rtp_multicast.c @@ -24,6 +24,8 @@ * * \author Joshua Colp * \author Andreas 'MacBrody' Brodmann + * + * \ingroup rtp_engines */ #include "asterisk.h"