loader: Flag module as declined in all cases where it fails to load.
authorCorey Farrell <git@cfware.com>
Thu, 4 Oct 2018 23:33:25 +0000 (19:33 -0400)
committerCorey Farrell <git@cfware.com>
Thu, 4 Oct 2018 23:40:47 +0000 (19:40 -0400)
This has no effect on startup since AST_MODULE_LOAD_FAILURE aborts
startup, but it's possible for this code to be returned on manual load
of a module after startup.

It is an error for a module to not have a load callback but this is not
a fatal system error.  In this case flag the module as declined, return
AST_MODULE_LOAD_FAILURE only if a required module is broken.

Expand doxygen documentation for AST_MODULE_LOAD_*.

Change-Id: I3c030bb917f6e5a0dfd9d91491a4661b348cabf8

include/asterisk/module.h
main/loader.c

index 08b4c43..2720d0e 100644 (file)
@@ -66,11 +66,40 @@ enum ast_module_unload_mode {
 };
 
 enum ast_module_load_result {
-       AST_MODULE_LOAD_SUCCESS = 0,    /*!< Module loaded and configured */
-       AST_MODULE_LOAD_DECLINE = 1,    /*!< Module is not configured */
-       AST_MODULE_LOAD_SKIP = 2,       /*!< Module was skipped for some reason (For loader.c use only. Should never be returned by modules)*/
-       AST_MODULE_LOAD_PRIORITY = 3,   /*!< Module is not loaded yet, but is added to priority list */
-       AST_MODULE_LOAD_FAILURE = -1,   /*!< Module could not be loaded properly */
+       /*! Module is loaded and configured. */
+       AST_MODULE_LOAD_SUCCESS = 0,
+       /*!
+        * \brief Module has failed to load, may be in an inconsistent state.
+        *
+        * This value is used when a module fails to start but does not risk
+        * system-wide stability.  Declined modules will prevent any other
+        * dependent module from starting.
+        */
+       AST_MODULE_LOAD_DECLINE = 1,
+       /*! \internal
+        * \brief Module was skipped for some reason.
+        *
+        * \note For loader.c use only. Should never be returned by modules.
+        */
+       AST_MODULE_LOAD_SKIP = 2,
+       /*! \internal
+        * \brief Module is not loaded yet, but is added to priority list.
+        *
+        * \note For loader.c use only. Should never be returned by modules.
+        */
+       AST_MODULE_LOAD_PRIORITY = 3,
+       /*!
+        * \brief Module could not be loaded properly.
+        *
+        * This return should only be returned by modules for unrecoverable
+        * failures that cause the whole system to become unstable.  In almost
+        * all cases \ref AST_MODULE_LOAD_DECLINE should be used instead.
+        *
+        * \warning Returning this code from any module will cause startup to abort.
+        * If startup is already completed this code has the same effect as
+        * \ref AST_MODULE_LOAD_DECLINE.
+        */
+       AST_MODULE_LOAD_FAILURE = -1,
 };
 
 /*!
index 865346f..3749c95 100644 (file)
@@ -1545,7 +1545,9 @@ static enum ast_module_load_result start_resource(struct ast_module *mod)
        }
 
        if (!mod->info->load) {
-               return AST_MODULE_LOAD_FAILURE;
+               mod->flags.declined = 1;
+
+               return mod->flags.required ? AST_MODULE_LOAD_FAILURE : AST_MODULE_LOAD_DECLINE;
        }
 
        if (module_deps_reference(mod, NULL)) {
@@ -1593,6 +1595,8 @@ static enum ast_module_load_result start_resource(struct ast_module *mod)
                }
                break;
        case AST_MODULE_LOAD_FAILURE:
+               mod->flags.declined = 1;
+               break;
        case AST_MODULE_LOAD_SKIP: /* modules should never return this value */
        case AST_MODULE_LOAD_PRIORITY:
                break;