Bug 65861 - [PATCH] Document how the post_config hook is called
Summary: [PATCH] Document how the post_config hook is called
Alias: None
Product: Apache httpd-2
Classification: Unclassified
Component: Documentation (show other bugs)
Version: 2.5-HEAD
Hardware: All All
: P2 normal (vote)
Target Milestone: ---
Assignee: HTTP Server Documentation List
Keywords: PatchAvailable
Depends on:
Reported: 2022-01-29 09:56 UTC by Daniel Shahaf
Modified: 2022-02-23 14:39 UTC (History)
1 user (show)


Note You need to log in before you can comment on or make changes to this bug.
Description Daniel Shahaf 2022-01-29 09:56:22 UTC
I've been able to find little information on the post_config hook in the project's documentation (doxygen, website, etc.).

I did find <https://cwiki.apache.org/confluence/display/HTTPD/ModuleLife>, but I don't know whether that page is up-to-date, considering that it hasn't been edited at least since it was imported from moin.

The following patch fleshes out the API documentation a bit.


1. Does not explain what post_config hooks are expected to do / not do in a pre-config invocation.  Is that assumed knowledge?  Is there an explanation of this elsewhere that can be pointed to?

2. A period may need to be added after the words "for each module".  I haven't run doxygen(1) on the file to check this.

3. The documentation of ap_state_query()-related macros includes some non-doxygen'd comments (/*…*/ rather than /**…*/), so API users will need to review the raw .h file to get all information.

Index: include/http_config.h
--- include/http_config.h       (revision 1897551)
+++ include/http_config.h       (working copy)
@@ -1350,6 +1350,16 @@ AP_DECLARE_HOOK(void,test_config,(apr_pool_t *pcon

  * Run the post_config function for each module
+ *
+ * The function might be called multiple times.  @a pconf, @a plog, and
+ * @a ptemp may be cleared and/or destroyed between calls.
+ *
+ * The function will be called zero or one times with the server's state being
+ * #AP_SQ_MS_CREATE_PRE_CONFIG, and will be called one or more times with
+ * the server's state being #AP_SQ_MS_CREATE_CONFIG.
+ *
+ * @see ap_state_query(), #AP_SQ_MAIN_STATE
+ *
  * @param pconf The config pool
  * @param plog The logging streams pool
  * @param ptemp The temporary pool
Comment 1 Rich Bowen 2022-02-23 14:39:28 UTC
Thanks. Applied in r1898347 (trunk) and r1898348 (2.4).