granicus.if.org Git - apache/blob - include/ap_mpm.h

   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
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /*
  37     The MPM, "multi-processing model" provides an abstraction of the
  38     interface with the OS for distributing incoming connections to
  39     threads/process for processing.  http_main invokes the MPM, and
  40     the MPM runs until a shutdown/restart has been indicated.
  41     The MPM calls out to the apache core via the ap_process_connection
  42     function when a connection arrives.
  43
  44     The MPM may or may not be multithreaded.  In the event that it is
  45     multithreaded, at any instant it guarantees a 1:1 mapping of threads
  46     ap_process_connection invocations.
  47
  48     Note: In the future it will be possible for ap_process_connection
  49     to return to the MPM prior to finishing the entire connection; and
  50     the MPM will proceed with asynchronous handling for the connection;
  51     in the future the MPM may call ap_process_connection again -- but
  52     does not guarantee it will occur on the same thread as the first call.
  53
  54     The MPM further guarantees that no asynchronous behaviour such as
  55     longjmps and signals will interfere with the user code that is
  56     invoked through ap_process_connection.  The MPM may reserve some
  57     signals for its use (i.e. SIGUSR1), but guarantees that these signals
  58     are ignored when executing outside the MPM code itself.  (This
  59     allows broken user code that does not handle EINTR to function
  60     properly.)
  61
  62     The suggested server restart and stop behaviour will be "graceful".
  63     However the MPM may choose to terminate processes when the user
  64     requests a non-graceful restart/stop.  When this occurs, the MPM kills
  65     all threads with extreme prejudice, and destroys the pchild pool.
  66     User cleanups registered in the pchild apr_pool_t will be invoked at
  67     this point.  (This can pose some complications, the user cleanups
  68     are asynchronous behaviour not unlike longjmp/signal... but if the
  69     admin is asking for a non-graceful shutdown, how much effort should
  70     we put into doing it in a nice way?)
  71
  72     unix/posix notes:
  73     - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
  74         But the preferred method of handling timeouts is to use the
  75         timeouts provided by the BUFF abstraction.
  76     - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
  77         for any of their own processing, it must be restored to SIG_IGN
  78         prior to executing or returning to any apache code.
  79     TODO: add SIGPIPE debugging check somewhere to make sure it's SIG_IGN
  80 */
  81
  82 /**
  83  * Pass control to the MPM for steady-state processing.  It is responsible
  84  * for controlling the parent and child processes.  It will run until a
  85  * restart/shutdown is indicated.
  86  * @param pconf the configuration pool, reset before the config file is read
  87  * @param plog the log pool, reset after the config file is read
  88  * @param server_conf the global server config.
  89  * @return DONE for shutdown OK otherwise.
  90  */
  91 AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf))
  92
  93 /**
  94  * Spawn a process with privileges that another module has requested
  95  * @param r The request_rec of the current request
  96  * @param newproc The resulting process handle.
  97  * @param progname The program to run
  98  * @param args the arguments to pass to the new program.  The first
  99  *                   one should be the program name.
 100  * @param env The new environment apr_table_t for the new process.  This
 101  *            should be a list of NULL-terminated strings.
 102  * @param attr the procattr we should use to determine how to create the new
 103  *         process
 104  * @param p The pool to use.
 105  */
 106 AP_DECLARE(apr_status_t) ap_os_create_privileged_process(
 107     const request_rec *r,
 108     apr_proc_t *newproc,
 109     const char *progname,
 110     const char * const *args,
 111     const char * const *env,
 112     apr_procattr_t *attr,
 113     apr_pool_t *p);
 114
 115 /* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED        */
 116 #define AP_MPMQ_NOT_SUPPORTED      0  /* This value specifies that an */
 117                                       /* MPM is not capable of        */
 118                                       /* threading or forking.        */
 119 #define AP_MPMQ_STATIC             1  /* This value specifies that    */
 120                                       /* an MPM is using a static     */
 121                                       /* number of threads or daemons */
 122 #define AP_MPMQ_DYNAMIC            2  /* This value specifies that    */
 123                                       /* an MPM is using a dynamic    */
 124                                       /* number of threads or daemons */
 125
 126 /* Values returned for AP_MPMQ_MPM_STATE */
 127 #define AP_MPMQ_STARTING              0
 128 #define AP_MPMQ_RUNNING               1
 129 #define AP_MPMQ_STOPPING              2
 130
 131 #define AP_MPMQ_MAX_DAEMON_USED       1  /* Max # of daemons used so far */
 132 #define AP_MPMQ_IS_THREADED           2  /* MPM can do threading         */
 133 #define AP_MPMQ_IS_FORKED             3  /* MPM can do forking           */
 134 #define AP_MPMQ_HARD_LIMIT_DAEMONS    4  /* The compiled max # daemons   */
 135 #define AP_MPMQ_HARD_LIMIT_THREADS    5  /* The compiled max # threads   */
 136 #define AP_MPMQ_MAX_THREADS           6  /* # of threads/child by config */
 137 #define AP_MPMQ_MIN_SPARE_DAEMONS     7  /* Min # of spare daemons       */
 138 #define AP_MPMQ_MIN_SPARE_THREADS     8  /* Min # of spare threads       */
 139 #define AP_MPMQ_MAX_SPARE_DAEMONS     9  /* Max # of spare daemons       */
 140 #define AP_MPMQ_MAX_SPARE_THREADS    10  /* Max # of spare threads       */
 141 #define AP_MPMQ_MAX_REQUESTS_DAEMON  11  /* Max # of requests per daemon */
 142 #define AP_MPMQ_MAX_DAEMONS          12  /* Max # of daemons by config   */
 143 #define AP_MPMQ_MPM_STATE            13  /* starting, running, stopping  */
 144 #define AP_MPMQ_IS_ASYNC             14  /* MPM can process async connections  */
 145 #define AP_MPMQ_GENERATION           15  /* MPM generation */
 146 #define AP_MPMQ_HAS_SERF             16  /* MPM can drive serf internally  */
 147
 148 /**
 149  * Query a property of the current MPM.
 150  * @param query_code One of APM_MPMQ_*
 151  * @param result A location to place the result of the query
 152  * @return APR_EGENERAL if an mpm-query hook has not been registered;
 153  * APR_SUCCESS or APR_ENOTIMPL otherwise
 154  * @remark The MPM doesn't register the implementing hook until the
 155  * register_hooks hook is called, so modules cannot use ap_mpm_query()
 156  * until after that point.
 157  * @fn int ap_mpm_query(int query_code, int *result)
 158  */
 159 AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);
 160
 161
 162 typedef void (ap_mpm_callback_fn_t)(void *baton);
 163
 164 /* only added support in the Event MPM....  check for APR_ENOTIMPL */
 165 AP_DECLARE(apr_status_t) ap_mpm_register_timed_callback(apr_time_t t,
 166                                                        ap_mpm_callback_fn_t *cbfn,
 167                                                        void *baton);
 168
 169 /* Defining GPROF when compiling uses the moncontrol() function to
 170  * disable gprof profiling in the parent, and enable it only for
 171  * request processing in children (or in one_process mode).  It's
 172  * absolutely required to get useful gprof results under linux
 173  * because the profile itimers and such are disabled across a
 174  * fork().  It's probably useful elsewhere as well.
 175  */
 176 #ifdef GPROF
 177 extern void moncontrol(int);
 178 #define AP_MONCONTROL(x) moncontrol(x)
 179 #else
 180 #define AP_MONCONTROL(x)
 181 #endif
 182
 183 #if AP_ENABLE_EXCEPTION_HOOK
 184 typedef struct ap_exception_info_t {
 185     int sig;
 186     pid_t pid;
 187 } ap_exception_info_t;
 188
 189 AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei))
 190 #endif /*AP_ENABLE_EXCEPTION_HOOK*/
 191
 192 #ifdef __cplusplus
 193 }
 194 #endif
 195
 196 #endif
 197 /** @} */