#include "apr_thread_proc.h"
#include "httpd.h"
+#include "scoreboard.h"
#ifdef __cplusplus
extern "C" {
The MPM may or may not be multithreaded. In the event that it is
multithreaded, at any instant it guarantees a 1:1 mapping of threads
- ap_process_connection invocations.
+ ap_process_connection invocations.
Note: In the future it will be possible for ap_process_connection
to return to the MPM prior to finishing the entire connection; and
unix/posix notes:
- The MPM does not set a SIGALRM handler, user code may use SIGALRM.
- But the preferred method of handling timeouts is to use the
- timeouts provided by the BUFF abstraction.
+ But the preferred method of handling timeouts is to use the
+ timeouts provided by the BUFF abstraction.
- The proper setting for SIGPIPE is SIG_IGN, if user code changes it
for any of their own processing, it must be restored to SIG_IGN
- prior to executing or returning to any apache code.
+ prior to executing or returning to any apache code.
TODO: add SIGPIPE debugging check somewhere to make sure it's SIG_IGN
*/
* @param plog the log pool, reset after the config file is read
* @param server_conf the global server config.
* @return DONE for shutdown OK otherwise.
+ * @ingroup hooks
*/
AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf))
* Spawn a process with privileges that another module has requested
* @param r The request_rec of the current request
* @param newproc The resulting process handle.
- * @param progname The program to run
- * @param args the arguments to pass to the new program. The first
+ * @param progname The program to run
+ * @param args the arguments to pass to the new program. The first
* one should be the program name.
- * @param env The new environment apr_table_t for the new process. This
+ * @param env The new environment apr_table_t for the new process. This
* should be a list of NULL-terminated strings.
* @param attr the procattr we should use to determine how to create the new
* process
- * @param p The pool to use.
+ * @param p The pool to use.
*/
AP_DECLARE(apr_status_t) ap_os_create_privileged_process(
const request_rec *r,
- apr_proc_t *newproc,
+ apr_proc_t *newproc,
const char *progname,
- const char * const *args,
+ const char * const *args,
const char * const *env,
- apr_procattr_t *attr,
+ apr_procattr_t *attr,
apr_pool_t *p);
-/* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED */
-#define AP_MPMQ_NOT_SUPPORTED 0 /* This value specifies that an */
- /* MPM is not capable of */
- /* threading or forking. */
-#define AP_MPMQ_STATIC 1 /* This value specifies that */
- /* an MPM is using a static */
- /* number of threads or daemons */
-#define AP_MPMQ_DYNAMIC 2 /* This value specifies that */
- /* an MPM is using a dynamic */
- /* number of threads or daemons */
-
-/* Values returned for AP_MPMQ_MPM_STATE */
+/** @defgroup mpmq MPM query
+ * @{
+ */
+
+/** @defgroup thrdfrk Subtypes/Values returned for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED
+ * @ingroup mpmq
+ * @{
+ */
+#define AP_MPMQ_NOT_SUPPORTED 0 /**< This value specifies that an
+ * MPM is not capable of
+ * threading or forking. */
+#define AP_MPMQ_STATIC 1 /**< This value specifies that
+ * an MPM is using a static
+ * number of threads or daemons */
+#define AP_MPMQ_DYNAMIC 2 /**< This value specifies that
+ * an MPM is using a dynamic
+ * number of threads or daemons */
+/** @} */
+
+/** @defgroup qstate Values returned for AP_MPMQ_MPM_STATE
+ * @ingroup mpmq
+ * @{
+ */
#define AP_MPMQ_STARTING 0
#define AP_MPMQ_RUNNING 1
#define AP_MPMQ_STOPPING 2
+/** @} */
-#define AP_MPMQ_MAX_DAEMON_USED 1 /* Max # of daemons used so far */
-#define AP_MPMQ_IS_THREADED 2 /* MPM can do threading */
-#define AP_MPMQ_IS_FORKED 3 /* MPM can do forking */
-#define AP_MPMQ_HARD_LIMIT_DAEMONS 4 /* The compiled max # daemons */
-#define AP_MPMQ_HARD_LIMIT_THREADS 5 /* The compiled max # threads */
-#define AP_MPMQ_MAX_THREADS 6 /* # of threads/child by config */
-#define AP_MPMQ_MIN_SPARE_DAEMONS 7 /* Min # of spare daemons */
-#define AP_MPMQ_MIN_SPARE_THREADS 8 /* Min # of spare threads */
-#define AP_MPMQ_MAX_SPARE_DAEMONS 9 /* Max # of spare daemons */
-#define AP_MPMQ_MAX_SPARE_THREADS 10 /* Max # of spare threads */
-#define AP_MPMQ_MAX_REQUESTS_DAEMON 11 /* Max # of requests per daemon */
-#define AP_MPMQ_MAX_DAEMONS 12 /* Max # of daemons by config */
-#define AP_MPMQ_MPM_STATE 13 /* starting, running, stopping */
-#define AP_MPMQ_IS_ASYNC 14 /* MPM can process async connections */
-#define AP_MPMQ_GENERATION 15 /* MPM generation */
-#define AP_MPMQ_HAS_SERF 16 /* MPM can drive serf internally */
+/** @defgroup qcodes Query codes for ap_mpm_query()
+ * @ingroup mpmq
+ * @{
+ */
+/** Max # of daemons used so far */
+#define AP_MPMQ_MAX_DAEMON_USED 1
+/** MPM can do threading */
+#define AP_MPMQ_IS_THREADED 2
+/** MPM can do forking */
+#define AP_MPMQ_IS_FORKED 3
+/** The compiled max # daemons */
+#define AP_MPMQ_HARD_LIMIT_DAEMONS 4
+/** The compiled max # threads */
+#define AP_MPMQ_HARD_LIMIT_THREADS 5
+/** \# of threads/child by config */
+#define AP_MPMQ_MAX_THREADS 6
+/** Min # of spare daemons */
+#define AP_MPMQ_MIN_SPARE_DAEMONS 7
+/** Min # of spare threads */
+#define AP_MPMQ_MIN_SPARE_THREADS 8
+/** Max # of spare daemons */
+#define AP_MPMQ_MAX_SPARE_DAEMONS 9
+/** Max # of spare threads */
+#define AP_MPMQ_MAX_SPARE_THREADS 10
+/** Max # of requests per daemon */
+#define AP_MPMQ_MAX_REQUESTS_DAEMON 11
+/** Max # of daemons by config */
+#define AP_MPMQ_MAX_DAEMONS 12
+/** starting, running, stopping */
+#define AP_MPMQ_MPM_STATE 13
+/** MPM can process async connections */
+#define AP_MPMQ_IS_ASYNC 14
+/** MPM generation */
+#define AP_MPMQ_GENERATION 15
+/** MPM can drive serf internally */
+#define AP_MPMQ_HAS_SERF 16
+/** MPM supports suspending/resuming connections */
+#define AP_MPMQ_CAN_SUSPEND 17
+/** @} */
/**
* Query a property of the current MPM.
- * @param query_code One of APM_MPMQ_*
+ * @param query_code One of AP_MPMQ_*
* @param result A location to place the result of the query
* @return APR_EGENERAL if an mpm-query hook has not been registered;
* APR_SUCCESS or APR_ENOTIMPL otherwise
*/
AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);
+/** @} */
typedef void (ap_mpm_callback_fn_t)(void *baton);
+/* only added support in the Event MPM.... check for APR_ENOTIMPL */
+AP_DECLARE(apr_status_t) ap_mpm_resume_suspended(conn_rec *c);
/* only added support in the Event MPM.... check for APR_ENOTIMPL */
AP_DECLARE(apr_status_t) ap_mpm_register_timed_callback(apr_time_t t,
ap_mpm_callback_fn_t *cbfn,
void *baton);
-
+
+/**
+ * Register a callback on the readability or writability on a group of sockets
+ * @param s Null-terminated list of sockets
+ * @param p pool for use between registration and callback
+ * @param for_read Whether the sockets are monitored for read or writability
+ * @param cbfn The callback function
+ * @param baton userdata for the callback function
+ * @return APR_SUCCESS if all sockets could be added to a pollset,
+ * APR_ENOTIMPL if no asynch support, or an apr_pollset_add error.
+ * @remark When activity is found on any 1 socket in the list, all are removed
+ * from the pollset and only 1 callback is issued.
+ */
+
+AP_DECLARE(apr_status_t) ap_mpm_register_socket_callback(apr_socket_t **s,
+ apr_pool_t *p,
+ int for_read,
+ ap_mpm_callback_fn_t *cbfn,
+ void *baton);
+ /**
+ * Register a callback on the readability or writability on a group of sockets, with a timeout
+ * @param s Null-terminated list of sockets
+ * @param p pool for use between registration and callback
+ * @param for_read Whether the sockets are monitored for read or writability
+ * @param cbfn The callback function
+ * @param tofn The callback function if the timeout expires
+ * @param baton userdata for the callback function
+ * @param timeout timeout for I/O in microseconds, unlimited if <= 0
+ * @return APR_SUCCESS if all sockets could be added to a pollset,
+ * APR_ENOTIMPL if no asynch support, or an apr_pollset_add error.
+ * @remark When activity is found on any 1 socket in the list, all are removed
+ * from the pollset and only 1 callback is issued.
+ * @remark For each call, only one of tofn or cbfn will be called, never both.
+ */
+
+AP_DECLARE(apr_status_t) ap_mpm_register_socket_callback_timeout(apr_socket_t **s,
+ apr_pool_t *p,
+ int for_read,
+ ap_mpm_callback_fn_t *cbfn,
+ ap_mpm_callback_fn_t *tofn,
+ void *baton,
+ apr_time_t timeout);
+
+
+AP_DECLARE(apr_status_t) ap_mpm_unregister_socket_callback(apr_socket_t **s,
+ apr_pool_t *p);
+
+typedef enum mpm_child_status {
+ MPM_CHILD_STARTED,
+ MPM_CHILD_EXITED,
+ MPM_CHILD_LOST_SLOT
+} mpm_child_status;
+
+/**
+ * Allow a module to remain aware of MPM child process state changes,
+ * along with the generation and scoreboard slot of the process changing
+ * state.
+ *
+ * With some MPMs (event and worker), an active MPM child process may lose
+ * its scoreboard slot if the child process is exiting and the scoreboard
+ * slot is needed by other processes. When this occurs, the hook will be
+ * called with the MPM_CHILD_LOST_SLOT state.
+ *
+ * @param s The main server_rec.
+ * @param pid The id of the MPM child process.
+ * @param gen The server generation of that child process.
+ * @param slot The scoreboard slot number, or -1. It will be -1 when an
+ * MPM child process exits, and that child had previously lost its
+ * scoreboard slot.
+ * @param state One of the mpm_child_status values. Modules should ignore
+ * unrecognized values.
+ * @ingroup hooks
+ */
+AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen,
+ int slot, mpm_child_status state))
+
+/**
+ * Allow a module to be notified when the last child process of a generation
+ * exits.
+ *
+ * @param s The main server_rec.
+ * @param gen The server generation which is now completely finished.
+ * @ingroup hooks
+ */
+AP_DECLARE_HOOK(void,end_generation,(server_rec *s, ap_generation_t gen))
+
/* Defining GPROF when compiling uses the moncontrol() function to
* disable gprof profiling in the parent, and enable it only for
* request processing in children (or in one_process mode). It's
#define AP_MONCONTROL(x)
#endif
-#if AP_ENABLE_EXCEPTION_HOOK
+#ifdef AP_ENABLE_EXCEPTION_HOOK
typedef struct ap_exception_info_t {
int sig;
pid_t pid;
} ap_exception_info_t;
+/**
+ * Run the fatal_exception hook for each module; this hook is run
+ * from some MPMs in the event of a child process crash, if the
+ * server was built with --enable-exception-hook and the
+ * EnableExceptionHook directive is On.
+ * @param ei information about the exception
+ * @ingroup hooks
+ */
AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei))
#endif /*AP_ENABLE_EXCEPTION_HOOK*/
projects / apache / blobdiff