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 #include "scoreboard.h"
  32
  33 #ifdef __cplusplus
  34 extern "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  * @ingroup hooks
  92  */
  93 AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf))
  94
  95 /**
  96  * Spawn a process with privileges that another module has requested
  97  * @param r The request_rec of the current request
  98  * @param newproc The resulting process handle.
  99  * @param progname The program to run
 100  * @param args the arguments to pass to the new program.  The first
 101  *                   one should be the program name.
 102  * @param env The new environment apr_table_t for the new process.  This
 103  *            should be a list of NULL-terminated strings.
 104  * @param attr the procattr we should use to determine how to create the new
 105  *         process
 106  * @param p The pool to use.
 107  */
 108 AP_DECLARE(apr_status_t) ap_os_create_privileged_process(
 109     const request_rec *r,
 110     apr_proc_t *newproc,
 111     const char *progname,
 112     const char * const *args,
 113     const char * const *env,
 114     apr_procattr_t *attr,
 115     apr_pool_t *p);
 116
 117 /** @defgroup mpmq MPM query
 118  * @{
 119  */
 120
 121 /** @defgroup thrdfrk Subtypes/Values returned for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED
 122  *  @ingroup mpmq
 123  *  @{
 124  */
 125 #define AP_MPMQ_NOT_SUPPORTED      0  /**< This value specifies that an
 126                                        * MPM is not capable of
 127                                        * threading or forking.        */
 128 #define AP_MPMQ_STATIC             1  /**< This value specifies that
 129                                        * an MPM is using a static
 130                                        * number of threads or daemons */
 131 #define AP_MPMQ_DYNAMIC            2  /**< This value specifies that
 132                                        * an MPM is using a dynamic
 133                                        * number of threads or daemons */
 134 /** @} */
 135
 136 /** @defgroup qstate Values returned for AP_MPMQ_MPM_STATE
 137  *  @ingroup mpmq
 138  *  @{
 139  */
 140 #define AP_MPMQ_STARTING              0
 141 #define AP_MPMQ_RUNNING               1
 142 #define AP_MPMQ_STOPPING              2
 143 /** @} */
 144
 145 /** @defgroup qcodes Query codes for ap_mpm_query()
 146  *  @ingroup mpmq
 147  *  @{
 148  */
 149 /** Max # of daemons used so far */
 150 #define AP_MPMQ_MAX_DAEMON_USED       1
 151 /** MPM can do threading         */
 152 #define AP_MPMQ_IS_THREADED           2
 153 /** MPM can do forking           */
 154 #define AP_MPMQ_IS_FORKED             3
 155 /** The compiled max # daemons   */
 156 #define AP_MPMQ_HARD_LIMIT_DAEMONS    4
 157 /** The compiled max # threads   */
 158 #define AP_MPMQ_HARD_LIMIT_THREADS    5
 159 /** \# of threads/child by config */
 160 #define AP_MPMQ_MAX_THREADS           6
 161 /** Min # of spare daemons       */
 162 #define AP_MPMQ_MIN_SPARE_DAEMONS     7
 163 /** Min # of spare threads       */
 164 #define AP_MPMQ_MIN_SPARE_THREADS     8
 165 /** Max # of spare daemons       */
 166 #define AP_MPMQ_MAX_SPARE_DAEMONS     9
 167 /** Max # of spare threads       */
 168 #define AP_MPMQ_MAX_SPARE_THREADS    10
 169 /** Max # of requests per daemon */
 170 #define AP_MPMQ_MAX_REQUESTS_DAEMON  11
 171 /** Max # of daemons by config   */
 172 #define AP_MPMQ_MAX_DAEMONS          12
 173 /** starting, running, stopping  */
 174 #define AP_MPMQ_MPM_STATE            13
 175 /** MPM can process async connections  */
 176 #define AP_MPMQ_IS_ASYNC             14
 177 /** MPM generation */
 178 #define AP_MPMQ_GENERATION           15
 179 /** MPM can drive serf internally  */
 180 #define AP_MPMQ_HAS_SERF             16
 181 /** MPM supports suspending/resuming connections */
 182 #define AP_MPMQ_CAN_SUSPEND          17
 183 /** @} */
 184
 185 /**
 186  * Query a property of the current MPM.
 187  * @param query_code One of AP_MPMQ_*
 188  * @param result A location to place the result of the query
 189  * @return APR_EGENERAL if an mpm-query hook has not been registered;
 190  * APR_SUCCESS or APR_ENOTIMPL otherwise
 191  * @remark The MPM doesn't register the implementing hook until the
 192  * register_hooks hook is called, so modules cannot use ap_mpm_query()
 193  * until after that point.
 194  * @fn int ap_mpm_query(int query_code, int *result)
 195  */
 196 AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);
 197
 198 /** @} */
 199
 200 typedef void (ap_mpm_callback_fn_t)(void *baton);
 201
 202 /* only added support in the Event MPM....  check for APR_ENOTIMPL */
 203 AP_DECLARE(apr_status_t) ap_mpm_resume_suspended(conn_rec *c);
 204 /* only added support in the Event MPM....  check for APR_ENOTIMPL */
 205 AP_DECLARE(apr_status_t) ap_mpm_register_timed_callback(apr_time_t t,
 206                                                        ap_mpm_callback_fn_t *cbfn,
 207                                                        void *baton);
 208
 209 /**
 210  * Register a callback on the readability or writability on a group of sockets
 211  * @param s Null-terminated list of sockets
 212  * @param p pool for use between registration and callback
 213  * @param for_read Whether the sockets are monitored for read or writability
 214  * @param cbfn The callback function
 215  * @param baton userdata for the callback function
 216  * @return APR_SUCCESS if all sockets could be added to a pollset,
 217  * APR_ENOTIMPL if no asynch support, or an apr_pollset_add error.
 218  * @remark When activity is found on any 1 socket in the list, all are removed
 219  * from the pollset and only 1 callback is issued.
 220  */
 221
 222 AP_DECLARE(apr_status_t) ap_mpm_register_socket_callback(apr_socket_t **s,
 223                                                          apr_pool_t *p,
 224                                                          int for_read,
 225                                                          ap_mpm_callback_fn_t *cbfn,
 226                                                          void *baton);
 227  /**
 228  * Register a callback on the readability or writability on a group of sockets, with a timeout
 229  * @param s Null-terminated list of sockets
 230  * @param p pool for use between registration and callback
 231  * @param for_read Whether the sockets are monitored for read or writability
 232  * @param cbfn The callback function
 233  * @param tofn The callback function if the timeout expires
 234  * @param baton userdata for the callback function
 235  * @param timeout timeout for I/O in microseconds, unlimited if <= 0
 236  * @return APR_SUCCESS if all sockets could be added to a pollset,
 237  * APR_ENOTIMPL if no asynch support, or an apr_pollset_add error.
 238  * @remark When activity is found on any 1 socket in the list, all are removed
 239  * from the pollset and only 1 callback is issued.
 240  * @remark For each call, only one of tofn or cbfn will be called, never both.
 241  */
 242
 243 AP_DECLARE(apr_status_t) ap_mpm_register_socket_callback_timeout(apr_socket_t **s,
 244                                                          apr_pool_t *p,
 245                                                          int for_read,
 246                                                          ap_mpm_callback_fn_t *cbfn,
 247                                                          ap_mpm_callback_fn_t *tofn,
 248                                                          void *baton,
 249                                                          apr_time_t timeout);
 250
 251
 252 AP_DECLARE(apr_status_t) ap_mpm_unregister_socket_callback(apr_socket_t **s,
 253                                                            apr_pool_t *p);
 254
 255 typedef enum mpm_child_status {
 256     MPM_CHILD_STARTED,
 257     MPM_CHILD_EXITED,
 258     MPM_CHILD_LOST_SLOT
 259 } mpm_child_status;
 260
 261 /**
 262  * Allow a module to remain aware of MPM child process state changes,
 263  * along with the generation and scoreboard slot of the process changing
 264  * state.
 265  *
 266  * With some MPMs (event and worker), an active MPM child process may lose
 267  * its scoreboard slot if the child process is exiting and the scoreboard
 268  * slot is needed by other processes.  When this occurs, the hook will be
 269  * called with the MPM_CHILD_LOST_SLOT state.
 270  *
 271  * @param s The main server_rec.
 272  * @param pid The id of the MPM child process.
 273  * @param gen The server generation of that child process.
 274  * @param slot The scoreboard slot number, or -1.  It will be -1 when an
 275  * MPM child process exits, and that child had previously lost its
 276  * scoreboard slot.
 277  * @param state One of the mpm_child_status values.  Modules should ignore
 278  * unrecognized values.
 279  * @ingroup hooks
 280  */
 281 AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen,
 282                                    int slot, mpm_child_status state))
 283
 284 /**
 285  * Allow a module to be notified when the last child process of a generation
 286  * exits.
 287  *
 288  * @param s The main server_rec.
 289  * @param gen The server generation which is now completely finished.
 290  * @ingroup hooks
 291  */
 292 AP_DECLARE_HOOK(void,end_generation,(server_rec *s, ap_generation_t gen))
 293
 294 /* Defining GPROF when compiling uses the moncontrol() function to
 295  * disable gprof profiling in the parent, and enable it only for
 296  * request processing in children (or in one_process mode).  It's
 297  * absolutely required to get useful gprof results under linux
 298  * because the profile itimers and such are disabled across a
 299  * fork().  It's probably useful elsewhere as well.
 300  */
 301 #ifdef GPROF
 302 extern void moncontrol(int);
 303 #define AP_MONCONTROL(x) moncontrol(x)
 304 #else
 305 #define AP_MONCONTROL(x)
 306 #endif
 307
 308 #ifdef AP_ENABLE_EXCEPTION_HOOK
 309 typedef struct ap_exception_info_t {
 310     int sig;
 311     pid_t pid;
 312 } ap_exception_info_t;
 313
 314 /**
 315  * Run the fatal_exception hook for each module; this hook is run
 316  * from some MPMs in the event of a child process crash, if the
 317  * server was built with --enable-exception-hook and the
 318  * EnableExceptionHook directive is On.
 319  * @param ei information about the exception
 320  * @ingroup hooks
 321  */
 322 AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei))
 323 #endif /*AP_ENABLE_EXCEPTION_HOOK*/
 324
 325 #ifdef __cplusplus
 326 }
 327 #endif
 328
 329 #endif
 330 /** @} */