1/* Licensed to the Apache Software Foundation (ASF) under one or more 2 * contributor license agreements. See the NOTICE file distributed with 3 * this work for additional information regarding copyright ownership. 4 * The ASF licenses this file to You under the Apache License, Version 2.0 5 * (the "License"); you may not use this file except in compliance with 6 * the License. You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17/** 18 * @file ap_mpm.h 19 * @brief Apache Multi-Processing Module library 20 * 21 * @defgroup APACHE_CORE_MPM Multi-Processing Module library 22 * @ingroup APACHE_CORE 23 * @{ 24 */ 25 26#ifndef AP_MPM_H 27#define AP_MPM_H 28 29#include "apr_thread_proc.h" 30#include "httpd.h" 31#include "scoreboard.h" 32 33#ifdef __cplusplus 34extern "C" { 35#endif 36 37/* 38 The MPM, "multi-processing model" provides an abstraction of the 39 interface with the OS for distributing incoming connections to 40 threads/process for processing. http_main invokes the MPM, and 41 the MPM runs until a shutdown/restart has been indicated. 42 The MPM calls out to the apache core via the ap_process_connection 43 function when a connection arrives. 44 45 The MPM may or may not be multithreaded. In the event that it is 46 multithreaded, at any instant it guarantees a 1:1 mapping of threads 47 ap_process_connection invocations. 48 49 Note: In the future it will be possible for ap_process_connection 50 to return to the MPM prior to finishing the entire connection; and 51 the MPM will proceed with asynchronous handling for the connection; 52 in the future the MPM may call ap_process_connection again -- but 53 does not guarantee it will occur on the same thread as the first call. 54 55 The MPM further guarantees that no asynchronous behaviour such as 56 longjmps and signals will interfere with the user code that is 57 invoked through ap_process_connection. The MPM may reserve some 58 signals for its use (i.e. SIGUSR1), but guarantees that these signals 59 are ignored when executing outside the MPM code itself. (This 60 allows broken user code that does not handle EINTR to function 61 properly.) 62 63 The suggested server restart and stop behaviour will be "graceful". 64 However the MPM may choose to terminate processes when the user 65 requests a non-graceful restart/stop. When this occurs, the MPM kills 66 all threads with extreme prejudice, and destroys the pchild pool. 67 User cleanups registered in the pchild apr_pool_t will be invoked at 68 this point. (This can pose some complications, the user cleanups 69 are asynchronous behaviour not unlike longjmp/signal... but if the 70 admin is asking for a non-graceful shutdown, how much effort should 71 we put into doing it in a nice way?) 72 73 unix/posix notes: 74 - The MPM does not set a SIGALRM handler, user code may use SIGALRM. 75 But the preferred method of handling timeouts is to use the 76 timeouts provided by the BUFF abstraction. 77 - The proper setting for SIGPIPE is SIG_IGN, if user code changes it 78 for any of their own processing, it must be restored to SIG_IGN 79 prior to executing or returning to any apache code. 80 TODO: add SIGPIPE debugging check somewhere to make sure it's SIG_IGN 81*/ 82 83/** 84 * Pass control to the MPM for steady-state processing. It is responsible 85 * for controlling the parent and child processes. It will run until a 86 * restart/shutdown is indicated. 87 * @param pconf the configuration pool, reset before the config file is read 88 * @param plog the log pool, reset after the config file is read 89 * @param server_conf the global server config. 90 * @return DONE for shutdown OK otherwise. 91 */ 92AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf)) 93 94/** 95 * Spawn a process with privileges that another module has requested 96 * @param r The request_rec of the current request 97 * @param newproc The resulting process handle. 98 * @param progname The program to run 99 * @param args the arguments to pass to the new program. The first 100 * one should be the program name. 101 * @param env The new environment apr_table_t for the new process. This 102 * should be a list of NULL-terminated strings. 103 * @param attr the procattr we should use to determine how to create the new 104 * process 105 * @param p The pool to use. 106 */ 107AP_DECLARE(apr_status_t) ap_os_create_privileged_process( 108 const request_rec *r, 109 apr_proc_t *newproc, 110 const char *progname, 111 const char * const *args, 112 const char * const *env, 113 apr_procattr_t *attr, 114 apr_pool_t *p); 115 116/* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED */ 117#define AP_MPMQ_NOT_SUPPORTED 0 /* This value specifies that an */ 118 /* MPM is not capable of */ 119 /* threading or forking. */ 120#define AP_MPMQ_STATIC 1 /* This value specifies that */ 121 /* an MPM is using a static */ 122 /* number of threads or daemons */ 123#define AP_MPMQ_DYNAMIC 2 /* This value specifies that */ 124 /* an MPM is using a dynamic */ 125 /* number of threads or daemons */ 126 127/* Values returned for AP_MPMQ_MPM_STATE */ 128#define AP_MPMQ_STARTING 0 129#define AP_MPMQ_RUNNING 1 130#define AP_MPMQ_STOPPING 2 131 132#define AP_MPMQ_MAX_DAEMON_USED 1 /* Max # of daemons used so far */ 133#define AP_MPMQ_IS_THREADED 2 /* MPM can do threading */ 134#define AP_MPMQ_IS_FORKED 3 /* MPM can do forking */ 135#define AP_MPMQ_HARD_LIMIT_DAEMONS 4 /* The compiled max # daemons */ 136#define AP_MPMQ_HARD_LIMIT_THREADS 5 /* The compiled max # threads */ 137#define AP_MPMQ_MAX_THREADS 6 /* # of threads/child by config */ 138#define AP_MPMQ_MIN_SPARE_DAEMONS 7 /* Min # of spare daemons */ 139#define AP_MPMQ_MIN_SPARE_THREADS 8 /* Min # of spare threads */ 140#define AP_MPMQ_MAX_SPARE_DAEMONS 9 /* Max # of spare daemons */ 141#define AP_MPMQ_MAX_SPARE_THREADS 10 /* Max # of spare threads */ 142#define AP_MPMQ_MAX_REQUESTS_DAEMON 11 /* Max # of requests per daemon */ 143#define AP_MPMQ_MAX_DAEMONS 12 /* Max # of daemons by config */ 144#define AP_MPMQ_MPM_STATE 13 /* starting, running, stopping */ 145#define AP_MPMQ_IS_ASYNC 14 /* MPM can process async connections */ 146#define AP_MPMQ_GENERATION 15 /* MPM generation */ 147#define AP_MPMQ_HAS_SERF 16 /* MPM can drive serf internally */ 148 149/** 150 * Query a property of the current MPM. 151 * @param query_code One of APM_MPMQ_* 152 * @param result A location to place the result of the query 153 * @return APR_EGENERAL if an mpm-query hook has not been registered; 154 * APR_SUCCESS or APR_ENOTIMPL otherwise 155 * @remark The MPM doesn't register the implementing hook until the 156 * register_hooks hook is called, so modules cannot use ap_mpm_query() 157 * until after that point. 158 * @fn int ap_mpm_query(int query_code, int *result) 159 */ 160AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result); 161 162 163typedef void (ap_mpm_callback_fn_t)(void *baton); 164 165/* only added support in the Event MPM.... check for APR_ENOTIMPL */ 166AP_DECLARE(apr_status_t) ap_mpm_register_timed_callback(apr_time_t t, 167 ap_mpm_callback_fn_t *cbfn, 168 void *baton); 169 170typedef enum mpm_child_status { 171 MPM_CHILD_STARTED, 172 MPM_CHILD_EXITED, 173 MPM_CHILD_LOST_SLOT 174} mpm_child_status; 175 176/** 177 * Allow a module to remain aware of MPM child process state changes, 178 * along with the generation and scoreboard slot of the process changing 179 * state. 180 * 181 * With some MPMs (event and worker), an active MPM child process may lose 182 * its scoreboard slot if the child process is exiting and the scoreboard 183 * slot is needed by other processes. When this occurs, the hook will be 184 * called with the MPM_CHILD_LOST_SLOT state. 185 * 186 * @param s The main server_rec. 187 * @param pid The id of the MPM child process. 188 * @param gen The server generation of that child process. 189 * @param slot The scoreboard slot number, or -1. It will be -1 when an 190 * MPM child process exits, and that child had previously lost its 191 * scoreboard slot. 192 * @param state One of the mpm_child_status values. Modules should ignore 193 * unrecognized values. 194 */ 195AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen, 196 int slot, mpm_child_status state)) 197 198/** 199 * Allow a module to be notified when the last child process of a generation 200 * exits. 201 * 202 * @param s The main server_rec. 203 * @param gen The server generation which is now completely finished. 204 */ 205AP_DECLARE_HOOK(void,end_generation,(server_rec *s, ap_generation_t gen)) 206 207/* Defining GPROF when compiling uses the moncontrol() function to 208 * disable gprof profiling in the parent, and enable it only for 209 * request processing in children (or in one_process mode). It's 210 * absolutely required to get useful gprof results under linux 211 * because the profile itimers and such are disabled across a 212 * fork(). It's probably useful elsewhere as well. 213 */ 214#ifdef GPROF 215extern void moncontrol(int); 216#define AP_MONCONTROL(x) moncontrol(x) 217#else 218#define AP_MONCONTROL(x) 219#endif 220 221#ifdef AP_ENABLE_EXCEPTION_HOOK 222typedef struct ap_exception_info_t { 223 int sig; 224 pid_t pid; 225} ap_exception_info_t; 226 227AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei)) 228#endif /*AP_ENABLE_EXCEPTION_HOOK*/ 229 230#ifdef __cplusplus 231} 232#endif 233 234#endif 235/** @} */ 236