<p>Friendly Automation <strong>submitted</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/19667">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span></span><br></pre><div style="white-space:pre-wrap">Approvals:
Joshua Colp: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">xmldoc: Allow XML docs to be reloaded.<br><br>The XML docs are currently only loaded on<br>startup with no way to update them during runtime.<br>This makes it impossible to load modules that<br>use ACO/Sorcery (which require documentation)<br>if they are added to the source tree and built while<br>Asterisk is running (e.g. external modules).<br><br>This adds a CLI command to reload the XML docs<br>during runtime so that documentation can be updated<br>without a full restart of Asterisk.<br><br>ASTERISK-30289 #close<br><br>Change-Id: I4f265b0e5517e757c5453a0f241201a5788d3a07<br>---<br>A doc/CHANGES-staging/xmldoc.txt<br>M main/config_options.c<br>M main/xmldoc.c<br>3 files changed, 131 insertions(+), 24 deletions(-)<br><br></pre>
<pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/doc/CHANGES-staging/xmldoc.txt b/doc/CHANGES-staging/xmldoc.txt</span><br><span>new file mode 100644</span><br><span>index 0000000..50324e4</span><br><span>--- /dev/null</span><br><span>+++ b/doc/CHANGES-staging/xmldoc.txt</span><br><span>@@ -0,0 +1,5 @@</span><br><span style="color: hsl(120, 100%, 40%);">+Subject: xmldocs</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The XML documentation can now be reloaded without restarting</span><br><span style="color: hsl(120, 100%, 40%);">+Asterisk, which makes it possible to load new modules that</span><br><span style="color: hsl(120, 100%, 40%);">+enforce documentation without restarting Asterisk.</span><br><span>diff --git a/main/config_options.c b/main/config_options.c</span><br><span>index c59a8b5..d258f60 100644</span><br><span>--- a/main/config_options.c</span><br><span>+++ b/main/config_options.c</span><br><span>@@ -1099,7 +1099,9 @@</span><br><span> }</span><br><span> </span><br><span> if (!(results = ast_xmldoc_query("/docs/configInfo[@name='%s']/configFile/configObject[@name='%s']", module, name))) {</span><br><span style="color: hsl(0, 100%, 40%);">- ast_log(LOG_WARNING, "Cannot update type '%s' in module '%s' because it has no existing documentation!\n", name, module);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_WARNING, "Cannot update type '%s' in module '%s' because it has no existing documentation!"</span><br><span style="color: hsl(120, 100%, 40%);">+ " If this module was recently built, run 'xmldoc reload' to refresh documentation, then load the module again\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ name, module);</span><br><span> return XMLDOC_STRICT ? -1 : 0;</span><br><span> }</span><br><span> </span><br><span>diff --git a/main/xmldoc.c b/main/xmldoc.c</span><br><span>index f924717..2b75523 100644</span><br><span>--- a/main/xmldoc.c</span><br><span>+++ b/main/xmldoc.c</span><br><span>@@ -68,9 +68,8 @@</span><br><span> /*!</span><br><span> * \brief Container of documentation trees</span><br><span> *</span><br><span style="color: hsl(0, 100%, 40%);">- * \note A RWLIST is a sufficient container type to use here for now.</span><br><span style="color: hsl(0, 100%, 40%);">- * However, some changes will need to be made to implement ref counting</span><br><span style="color: hsl(0, 100%, 40%);">- * if reload support is added in the future.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note A RWLIST is a sufficient container type to use, provided</span><br><span style="color: hsl(120, 100%, 40%);">+ * the list lock is always held while there are references to the list.</span><br><span> */</span><br><span> static AST_RWLIST_HEAD_STATIC(xmldoc_tree, documentation_tree);</span><br><span> </span><br><span>@@ -430,6 +429,8 @@</span><br><span> *</span><br><span> * \retval NULL on error.</span><br><span> * \retval A node of type ast_xml_node.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Must be called with a RDLOCK held on xmldoc_tree</span><br><span> */</span><br><span> static struct ast_xml_node *xmldoc_get_node(const char *type, const char *name, const char *module, const char *language)</span><br><span> {</span><br><span>@@ -438,7 +439,6 @@</span><br><span> struct ast_xml_node *lang_match = NULL;</span><br><span> struct documentation_tree *doctree;</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> AST_LIST_TRAVERSE(&xmldoc_tree, doctree, entry) {</span><br><span> /* the core xml documents have priority over thirdparty document. */</span><br><span> node = ast_xml_get_root(doctree->doc);</span><br><span>@@ -497,7 +497,6 @@</span><br><span> break;</span><br><span> }</span><br><span> }</span><br><span style="color: hsl(0, 100%, 40%);">- AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> </span><br><span> return node;</span><br><span> }</span><br><span>@@ -1253,13 +1252,18 @@</span><br><span> char *ast_xmldoc_build_syntax(const char *type, const char *name, const char *module)</span><br><span> {</span><br><span> struct ast_xml_node *node;</span><br><span style="color: hsl(120, 100%, 40%);">+ char *syntax;</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> if (!node) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- return _ast_xmldoc_build_syntax(node, type, name);</span><br><span style="color: hsl(120, 100%, 40%);">+ syntax = _ast_xmldoc_build_syntax(node, type, name);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ return syntax;</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span>@@ -1705,12 +1709,15 @@</span><br><span> }</span><br><span> </span><br><span> /* get the application/function root node. */</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> if (!node || !ast_xml_node_get_children(node)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span> output = _ast_xmldoc_build_seealso(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> </span><br><span> return output;</span><br><span> }</span><br><span>@@ -2077,18 +2084,23 @@</span><br><span> char *ast_xmldoc_build_arguments(const char *type, const char *name, const char *module)</span><br><span> {</span><br><span> struct ast_xml_node *node;</span><br><span style="color: hsl(120, 100%, 40%);">+ char *arguments;</span><br><span> </span><br><span> if (ast_strlen_zero(type) || ast_strlen_zero(name)) {</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> </span><br><span> if (!node || !ast_xml_node_get_children(node)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- return _ast_xmldoc_build_arguments(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ arguments = _ast_xmldoc_build_arguments(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ return arguments;</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span>@@ -2192,20 +2204,27 @@</span><br><span> static char *xmldoc_build_field(const char *type, const char *name, const char *module, const char *var, int raw)</span><br><span> {</span><br><span> struct ast_xml_node *node;</span><br><span style="color: hsl(120, 100%, 40%);">+ char *field;</span><br><span> </span><br><span> if (ast_strlen_zero(type) || ast_strlen_zero(name)) {</span><br><span> ast_log(LOG_ERROR, "Tried to look in XML tree with faulty values.\n");</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> </span><br><span> if (!node) {</span><br><span style="color: hsl(0, 100%, 40%);">- ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation\n", type, name);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_WARNING, "Couldn't find %s %s in XML documentation"</span><br><span style="color: hsl(120, 100%, 40%);">+ " If this module was recently built, run 'xmldoc reload' to refresh documentation\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ type, name);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- return _xmldoc_build_field(node, var, raw);</span><br><span style="color: hsl(120, 100%, 40%);">+ field = _xmldoc_build_field(node, var, raw);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ return field;</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span>@@ -2465,18 +2484,23 @@</span><br><span> struct ast_xml_doc_item *ast_xmldoc_build_list_responses(const char *type, const char *name, const char *module)</span><br><span> {</span><br><span> struct ast_xml_node *node;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct ast_xml_doc_item *responses;</span><br><span> </span><br><span> if (ast_strlen_zero(type) || ast_strlen_zero(name)) {</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> </span><br><span> if (!node || !ast_xml_node_get_children(node)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- return xmldoc_build_list_responses(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ responses = xmldoc_build_list_responses(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ return responses;</span><br><span> }</span><br><span> </span><br><span> /*!</span><br><span>@@ -2530,18 +2554,23 @@</span><br><span> struct ast_xml_doc_item *ast_xmldoc_build_final_response(const char *type, const char *name, const char *module)</span><br><span> {</span><br><span> struct ast_xml_node *node;</span><br><span style="color: hsl(120, 100%, 40%);">+ static struct ast_xml_doc_item *response;</span><br><span> </span><br><span> if (ast_strlen_zero(type) || ast_strlen_zero(name)) {</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_RDLOCK(&xmldoc_tree);</span><br><span> node = xmldoc_get_node(type, name, module, documentation_language);</span><br><span> </span><br><span> if (!node || !ast_xml_node_get_children(node)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> return NULL;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- return xmldoc_build_final_response(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ response = xmldoc_build_final_response(node);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ return response;</span><br><span> }</span><br><span> </span><br><span> struct ast_xml_xpath_results *__attribute__((format(printf, 1, 2))) ast_xmldoc_query(const char *fmt, ...)</span><br><span>@@ -2860,25 +2889,35 @@</span><br><span> </span><br><span> static struct ast_cli_entry cli_dump_xmldocs = AST_CLI_DEFINE(handle_dump_docs, "Dump the XML docs to the specified file");</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-/*! \brief Close and unload XML documentation. */</span><br><span style="color: hsl(0, 100%, 40%);">-static void xmldoc_unload_documentation(void)</span><br><span style="color: hsl(120, 100%, 40%);">+static char *handle_reload_docs(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a);</span><br><span style="color: hsl(120, 100%, 40%);">+static struct ast_cli_entry cli_reload_xmldocs = AST_CLI_DEFINE(handle_reload_docs, "Reload the XML docs");</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! \note Must be called with xmldoc_tree locked */</span><br><span style="color: hsl(120, 100%, 40%);">+static void xmldoc_purge_documentation(void)</span><br><span> {</span><br><span> struct documentation_tree *doctree;</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- ast_cli_unregister(&cli_dump_xmldocs);</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- AST_RWLIST_WRLOCK(&xmldoc_tree);</span><br><span> while ((doctree = AST_RWLIST_REMOVE_HEAD(&xmldoc_tree, entry))) {</span><br><span> ast_free(doctree->filename);</span><br><span> ast_xml_close(doctree->doc);</span><br><span> ast_free(doctree);</span><br><span> }</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! \brief Close and unload XML documentation. */</span><br><span style="color: hsl(120, 100%, 40%);">+static void xmldoc_unload_documentation(void)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_cli_unregister(&cli_reload_xmldocs);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_cli_unregister(&cli_dump_xmldocs);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_RWLIST_WRLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+ xmldoc_purge_documentation();</span><br><span> AST_RWLIST_UNLOCK(&xmldoc_tree);</span><br><span> </span><br><span> ast_xml_finish();</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-int ast_xmldoc_load_documentation(void)</span><br><span style="color: hsl(120, 100%, 40%);">+static int xmldoc_load_documentation(int first_time)</span><br><span> {</span><br><span> struct ast_xml_node *root_node;</span><br><span> struct ast_xml_doc *tmpdoc;</span><br><span>@@ -2907,12 +2946,14 @@</span><br><span> ast_config_destroy(cfg);</span><br><span> }</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">- /* initialize the XML library. */</span><br><span style="color: hsl(0, 100%, 40%);">- ast_xml_init();</span><br><span style="color: hsl(0, 100%, 40%);">-</span><br><span style="color: hsl(0, 100%, 40%);">- ast_cli_register(&cli_dump_xmldocs);</span><br><span style="color: hsl(0, 100%, 40%);">- /* register function to be run when asterisk finish. */</span><br><span style="color: hsl(0, 100%, 40%);">- ast_register_cleanup(xmldoc_unload_documentation);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (first_time) {</span><br><span style="color: hsl(120, 100%, 40%);">+ /* initialize the XML library. */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_xml_init();</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_cli_register(&cli_dump_xmldocs);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_cli_register(&cli_reload_xmldocs);</span><br><span style="color: hsl(120, 100%, 40%);">+ /* register function to be run when asterisk finish. */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_register_cleanup(xmldoc_unload_documentation);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span> </span><br><span> globbuf.gl_offs = 0; /* slots to reserve in gl_pathv */</span><br><span> </span><br><span>@@ -2942,6 +2983,16 @@</span><br><span> ast_free(xmlpattern);</span><br><span> </span><br><span> AST_RWLIST_WRLOCK(&xmldoc_tree);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!first_time) {</span><br><span style="color: hsl(120, 100%, 40%);">+ /* If we're reloading, purge the existing documentation.</span><br><span style="color: hsl(120, 100%, 40%);">+ * We do this with the lock held so that if somebody</span><br><span style="color: hsl(120, 100%, 40%);">+ * else tries to get documentation, there's no chance</span><br><span style="color: hsl(120, 100%, 40%);">+ * of retrieiving it after we purged the old docs</span><br><span style="color: hsl(120, 100%, 40%);">+ * but before we loaded the new ones. */</span><br><span style="color: hsl(120, 100%, 40%);">+ xmldoc_purge_documentation();</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> /* loop over expanded files */</span><br><span> for (i = 0; i < globbuf.gl_pathc; i++) {</span><br><span> /* check for duplicates (if we already [try to] open the same file. */</span><br><span>@@ -2993,4 +3044,31 @@</span><br><span> return 0;</span><br><span> }</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+int ast_xmldoc_load_documentation(void)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return xmldoc_load_documentation(1);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int xmldoc_reload_documentation(void)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return xmldoc_load_documentation(0);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static char *handle_reload_docs(struct ast_cli_entry *e, int cmd, struct ast_cli_args *a)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ switch (cmd) {</span><br><span style="color: hsl(120, 100%, 40%);">+ case CLI_INIT:</span><br><span style="color: hsl(120, 100%, 40%);">+ e->command = "xmldoc reload";</span><br><span style="color: hsl(120, 100%, 40%);">+ e->usage =</span><br><span style="color: hsl(120, 100%, 40%);">+ "Usage: xmldoc reload\n"</span><br><span style="color: hsl(120, 100%, 40%);">+ " Reload XML documentation\n";</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ case CLI_GENERATE:</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ xmldoc_reload_documentation();</span><br><span style="color: hsl(120, 100%, 40%);">+ return CLI_SUCCESS;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> #endif /* AST_XML_DOCS */</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/19667">change 19667</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/19667"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: 20 </div>
<div style="display:none"> Gerrit-Change-Id: I4f265b0e5517e757c5453a0f241201a5788d3a07 </div>
<div style="display:none"> Gerrit-Change-Number: 19667 </div>
<div style="display:none"> Gerrit-PatchSet: 2 </div>
<div style="display:none"> Gerrit-Owner: N A <asterisk@phreaknet.org> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Joshua Colp <jcolp@sangoma.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>