From 7058495f97436a204379cb727b230f421a8a4989 Mon Sep 17 00:00:00 2001 From: Olle Johansson Date: Tue, 28 Mar 2006 23:55:52 +0000 Subject: Doxygen fixes git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@15860 65c4cc65-6c06-0410-ace0-fbb531ad65f3 --- include/asterisk/module.h | 53 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 43 insertions(+), 10 deletions(-) (limited to 'include/asterisk') diff --git a/include/asterisk/module.h b/include/asterisk/module.h index f2065efc5..b00ec488d 100644 --- a/include/asterisk/module.h +++ b/include/asterisk/module.h @@ -41,7 +41,7 @@ extern "C" { #define STATIC_MODULE static /* symbols are static */ #endif -/* Every module should provide these functions */ +/*! \note Every module should provide these functions */ /*! * \brief Initialize the module. * @@ -285,8 +285,8 @@ struct localuser { AST_LIST_ENTRY(localuser) next; }; -/*! structure used for lock and refcount of module users. - * The mutex protects the usecnt field and whatever needs to be +/*! \brief structure used for lock and refcount of module users. + * \note The mutex protects the usecnt field and whatever needs to be * protected (typically, a list of struct localuser). * As a trick, if usecnt is initialized with -1, * ast_format_register will init the mutex for you. @@ -318,7 +318,7 @@ void ast_hangup_localusers(struct ast_module_lock *m); #define STANDARD_USECOUNT_DECL LOCAL_USER_DECL /* XXX lock remains unused */ -/*! run 'x' protected by lock, then call ast_update_use_count() */ +/*! \brief run 'x' protected by lock, then call ast_update_use_count() */ #define __MOD_PROTECT(x) do { \ ast_mutex_lock(&me.lock); \ x; \ @@ -381,8 +381,8 @@ void ast_hangup_localusers(struct ast_module_lock *m); */ #define STANDARD_USECOUNT(res) do { res = me.usecnt; } while (0) -/* - * XXX The following macro is deprecated, and only used by modules +/*! \brief Old usecount macro + * \note XXX The following macro is deprecated, and only used by modules * in codecs/ and a few other places which do their own manipulation * of the usecount variable. * Its use is supposed to be gradually phased away as those modules @@ -390,16 +390,18 @@ void ast_hangup_localusers(struct ast_module_lock *m); */ #define OLD_STANDARD_USECOUNT(res) do { res = localusecnt; } while (0) -/*! - * \brief The following is part of the new module management code. +/*! \page ModMngmnt The Asterisk Module management interface + * \par The following is part of the new module management code. * * All modules must implement the module API (load, unload...) * whose functions are exported through fields of a "struct module_symbol"; * * Modules exporting extra symbols (data or functions), should list - * them into an array of struct symbol_entry: + * them into an array of struct symbol_entry: \r * struct symbol_entry exported_symbols[] + * \r * of symbols, with a NULL name on the last entry + * * Functions should be added with MOD_FUNC(name), * data structures with MOD_DATA(_name). * The array in turn is referenced by struct module_symbol. @@ -407,6 +409,7 @@ void ast_hangup_localusers(struct ast_module_lock *m); * to a record containing all the methods. This is the API of the module, * and should be known to the module's clients as well. * + * \par Connections to symbols in other modules * Modules that require symbols supplied by other modules should * provide an array * struct symbol_entry required_symbols[] @@ -438,7 +441,7 @@ void ast_hangup_localusers(struct ast_module_lock *m); * .buf = buf, * } * - * NOTE: symbol names are 'global' in this module namespace, so it + * \note NOTE: symbol names are 'global' in this module namespace, so it * will be wiser to name exported symbols with a prefix indicating the module * supplying it, e.g. foo_f, foo_g, foo_buf. Internally to the module, * symbols are still static so they can keep short and meaningful names. @@ -451,6 +454,36 @@ void ast_hangup_localusers(struct ast_module_lock *m); * * Note that the loader requires that no fields of exported_symbols * are NULL, because that is used as an indication of the end of the array. + * + * \par Module states + * Modules can be in a number of different states, as below: + * - \b MS_FAILED attempt to load failed. This is final. + * - \b MS_NEW just added to the list, symbols unresolved. + * - \b MS_RESOLVED all symbols resolved, but supplier modules not active yet. + * - \b MS_CANLOAD all symbols resolved and suppliers are all active + * (or we are in a cyclic dependency and we are breaking a loop) + * - \b MS_ACTIVE load() returned successfully. + * + * + * \par Module Types + * For backward compatibility, we have 3 types of loadable modules: + * + * - \b MOD_0 these are the 'old style' modules, which export a number + * of callbacks, and their full interface, as globally visible + * symbols. The module needs to be loaded with RTLD_LAZY and + * RTLD_GLOBAL to make symbols visible to other modules, and + * to avoid load failures due to cross dependencies. + * + * - \b MOD_1 almost as above, but the generic callbacks are all into a + * a structure, mod_data. Same load requirements as above. + * + * - \b MOD_2 this is the 'new style' format for modules. The module must + * explictly declare which simbols are exported and which + * symbols from other modules are used, and the code in this + * loader will implement appropriate checks to load the modules + * in the correct order. Also this allows to load modules + * with RTLD_NOW and RTLD_LOCAL so there is no chance of run-time + * bugs due to unresolved symbols or name conflicts. */ struct symbol_entry { -- cgit v1.2.3