home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277256_ap_mpm.h < prev    next >
C/C++ Source or Header  |  2004-02-26  |  8KB  |  176 lines
  1. /* Copyright 1999-2004 The Apache Software Foundation
  2.  *
  3.  * Licensed under the Apache License, Version 2.0 (the "License");
  4.  * you may not use this file except in compliance with the License.
  5.  * You may obtain a copy of the License at
  6.  *
  7.  *     http://www.apache.org/licenses/LICENSE-2.0
  8.  *
  9.  * Unless required by applicable law or agreed to in writing, software
  10.  * distributed under the License is distributed on an "AS IS" BASIS,
  11.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12.  * See the License for the specific language governing permissions and
  13.  * limitations under the License.
  14.  */
  15.  
  16. #ifndef AP_MPM_H
  17. #define AP_MPM_H
  18.  
  19. #include "apr_thread_proc.h"
  20.  
  21. /**
  22.  * @package Multi-Processing Module library
  23.  */
  24.  
  25. /*
  26.     The MPM, "multi-processing model" provides an abstraction of the
  27.     interface with the OS for distributing incoming connections to
  28.     threads/process for processing.  http_main invokes the MPM, and
  29.     the MPM runs until a shutdown/restart has been indicated.
  30.     The MPM calls out to the apache core via the ap_process_connection
  31.     function when a connection arrives.
  32.  
  33.     The MPM may or may not be multithreaded.  In the event that it is
  34.     multithreaded, at any instant it guarantees a 1:1 mapping of threads
  35.     ap_process_connection invocations.  
  36.  
  37.     Note: In the future it will be possible for ap_process_connection
  38.     to return to the MPM prior to finishing the entire connection; and
  39.     the MPM will proceed with asynchronous handling for the connection;
  40.     in the future the MPM may call ap_process_connection again -- but
  41.     does not guarantee it will occur on the same thread as the first call.
  42.  
  43.     The MPM further guarantees that no asynchronous behaviour such as
  44.     longjmps and signals will interfere with the user code that is
  45.     invoked through ap_process_connection.  The MPM may reserve some
  46.     signals for its use (i.e. SIGUSR1), but guarantees that these signals
  47.     are ignored when executing outside the MPM code itself.  (This
  48.     allows broken user code that does not handle EINTR to function
  49.     properly.)
  50.  
  51.     The suggested server restart and stop behaviour will be "graceful".
  52.     However the MPM may choose to terminate processes when the user
  53.     requests a non-graceful restart/stop.  When this occurs, the MPM kills
  54.     all threads with extreme prejudice, and destroys the pchild pool.
  55.     User cleanups registered in the pchild apr_pool_t will be invoked at
  56.     this point.  (This can pose some complications, the user cleanups
  57.     are asynchronous behaviour not unlike longjmp/signal... but if the
  58.     admin is asking for a non-graceful shutdown, how much effort should
  59.     we put into doing it in a nice way?)
  60.  
  61.     unix/posix notes:
  62.     - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
  63.     But the preferred method of handling timeouts is to use the
  64.     timeouts provided by the BUFF abstraction.
  65.     - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
  66.         for any of their own processing, it must be restored to SIG_IGN
  67.     prior to executing or returning to any apache code.
  68.     TODO: add SIGPIPE debugging check somewhere to make sure it's SIG_IGN
  69. */
  70.  
  71. /**
  72.  * This is the function that MPMs must create.  This function is responsible
  73.  * for controlling the parent and child processes.  It will run until a 
  74.  * restart/shutdown is indicated.
  75.  * @param pconf the configuration pool, reset before the config file is read
  76.  * @param plog the log pool, reset after the config file is read
  77.  * @param server_conf the global server config.
  78.  * @return 1 for shutdown 0 otherwise.
  79.  * @deffunc int ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf)
  80.  */
  81. AP_DECLARE(int) ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf);
  82.  
  83. /**
  84.  * predicate indicating if a graceful stop has been requested ...
  85.  * used by the connection loop 
  86.  * @return 1 if a graceful stop has been requested, 0 otherwise
  87.  * @deffunc int ap_graceful_stop_signalled(*void)
  88.  */
  89. AP_DECLARE(int) ap_graceful_stop_signalled(void);
  90.  
  91. /**
  92.  * Spawn a process with privileges that another module has requested
  93.  * @param r The request_rec of the current request
  94.  * @param newproc The resulting process handle.
  95.  * @param progname The program to run 
  96.  * @param const_args the arguments to pass to the new program.  The first 
  97.  *                   one should be the program name.
  98.  * @param env The new environment apr_table_t for the new process.  This 
  99.  *            should be a list of NULL-terminated strings.
  100.  * @param attr the procattr we should use to determine how to create the new
  101.  *         process
  102.  * @param p The pool to use. 
  103.  */
  104. AP_DECLARE(apr_status_t) ap_os_create_privileged_process(
  105.     const request_rec *r,
  106.     apr_proc_t *newproc, 
  107.     const char *progname,
  108.     const char * const *args, 
  109.     const char * const *env,
  110.     apr_procattr_t *attr, 
  111.     apr_pool_t *p);
  112.  
  113. /* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED        */
  114. #define AP_MPMQ_NOT_SUPPORTED      0  /* This value specifies whether */
  115.                                       /* an MPM is capable of         */
  116.                                       /* threading or forking.        */
  117. #define AP_MPMQ_STATIC             1  /* This value specifies whether */
  118.                                       /* an MPM is using a static #   */
  119.                                       /* threads or daemons.          */
  120. #define AP_MPMQ_DYNAMIC            2  /* This value specifies whether */
  121.                                       /* an MPM is using a dynamic #  */
  122.                                       /* threads or daemons.          */
  123.  
  124. /* Values returned for AP_MPMQ_MPM_STATE */
  125. #define AP_MPMQ_STARTING              0
  126. #define AP_MPMQ_RUNNING               1
  127. #define AP_MPMQ_STOPPING              2
  128.  
  129. #define AP_MPMQ_MAX_DAEMON_USED       1  /* Max # of daemons used so far */
  130. #define AP_MPMQ_IS_THREADED           2  /* MPM can do threading         */
  131. #define AP_MPMQ_IS_FORKED             3  /* MPM can do forking           */
  132. #define AP_MPMQ_HARD_LIMIT_DAEMONS    4  /* The compiled max # daemons   */
  133. #define AP_MPMQ_HARD_LIMIT_THREADS    5  /* The compiled max # threads   */
  134. #define AP_MPMQ_MAX_THREADS           6  /* # of threads/child by config */
  135. #define AP_MPMQ_MIN_SPARE_DAEMONS     7  /* Min # of spare daemons       */
  136. #define AP_MPMQ_MIN_SPARE_THREADS     8  /* Min # of spare threads       */
  137. #define AP_MPMQ_MAX_SPARE_DAEMONS     9  /* Max # of spare daemons       */
  138. #define AP_MPMQ_MAX_SPARE_THREADS    10  /* Max # of spare threads       */
  139. #define AP_MPMQ_MAX_REQUESTS_DAEMON  11  /* Max # of requests per daemon */
  140. #define AP_MPMQ_MAX_DAEMONS          12  /* Max # of daemons by config   */
  141. #define AP_MPMQ_MPM_STATE            13  /* starting, running, stopping  */
  142.  
  143. /**
  144.  * Query a property of the current MPM.  
  145.  * @param query_code One of APM_MPMQ_*
  146.  * @param result A location to place the result of the query
  147.  * @return APR_SUCCESS or APR_ENOTIMPL
  148.  * @deffunc int ap_mpm_query(int query_code, int *result)
  149.  */
  150. AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);
  151.  
  152. /* Defining GPROF when compiling uses the moncontrol() function to
  153.  * disable gprof profiling in the parent, and enable it only for
  154.  * request processing in children (or in one_process mode).  It's
  155.  * absolutely required to get useful gprof results under linux
  156.  * because the profile itimers and such are disabled across a
  157.  * fork().  It's probably useful elsewhere as well.
  158.  */
  159. #ifdef GPROF
  160. extern void moncontrol(int);
  161. #define AP_MONCONTROL(x) moncontrol(x)
  162. #else
  163. #define AP_MONCONTROL(x)
  164. #endif
  165.  
  166. #if AP_ENABLE_EXCEPTION_HOOK
  167. typedef struct ap_exception_info_t {
  168.     int sig;
  169.     pid_t pid;
  170. } ap_exception_info_t;
  171.  
  172. AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei))
  173. #endif /*AP_ENABLE_EXCEPTION_HOOK*/
  174.  
  175. #endif
  176.