1 /* ====================================================================
2 * The Apache Software License, Version 1.1
4 * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions
11 * 1. Redistributions of source code must retain the above copyright
12 * notice, this list of conditions and the following disclaimer.
14 * 2. Redistributions in binary form must reproduce the above copyright
15 * notice, this list of conditions and the following disclaimer in
16 * the documentation and/or other materials provided with the
19 * 3. The end-user documentation included with the redistribution,
20 * if any, must include the following acknowledgment:
21 * "This product includes software developed by the
22 * Apache Software Foundation (http://www.apache.org/)."
23 * Alternately, this acknowledgment may appear in the software itself,
24 * if and wherever such third-party acknowledgments normally appear.
26 * 4. The names "Apache" and "Apache Software Foundation" must
27 * not be used to endorse or promote products derived from this
28 * software without prior written permission. For written
29 * permission, please contact apache@apache.org.
31 * 5. Products derived from this software may not be called "Apache",
32 * nor may "Apache" appear in their name, without prior written
33 * permission of the Apache Software Foundation.
35 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
36 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
37 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
41 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
42 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
43 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
44 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
45 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
47 * ====================================================================
49 * This software consists of voluntary contributions made by many
50 * individuals on behalf of the Apache Software Foundation. For more
51 * information on the Apache Software Foundation, please see
52 * <http://www.apache.org/>.
59 * @package Multi-Processing Module library
63 The MPM, "multi-processing model" provides an abstraction of the
64 interface with the OS for distributing incoming connections to
65 threads/process for processing. http_main invokes the MPM, and
66 the MPM runs until a shutdown/restart has been indicated.
67 The MPM calls out to the apache core via the ap_process_connection
68 function when a connection arrives.
70 The MPM may or may not be multithreaded. In the event that it is
71 multithreaded, at any instant it guarantees a 1:1 mapping of threads
72 ap_process_connection invocations.
74 Note: In the future it will be possible for ap_process_connection
75 to return to the MPM prior to finishing the entire connection; and
76 the MPM will proceed with asynchronous handling for the connection;
77 in the future the MPM may call ap_process_connection again -- but
78 does not guarantee it will occur on the same thread as the first call.
80 The MPM further guarantees that no asynchronous behaviour such as
81 longjmps and signals will interfere with the user code that is
82 invoked through ap_process_connection. The MPM may reserve some
83 signals for its use (i.e. SIGUSR1), but guarantees that these signals
84 are ignored when executing outside the MPM code itself. (This
85 allows broken user code that does not handle EINTR to function
88 The suggested server restart and stop behaviour will be "graceful".
89 However the MPM may choose to terminate processes when the user
90 requests a non-graceful restart/stop. When this occurs, the MPM kills
91 all threads with extreme prejudice, and destroys the pchild pool.
92 User cleanups registered in the pchild apr_pool_t will be invoked at
93 this point. (This can pose some complications, the user cleanups
94 are asynchronous behaviour not unlike longjmp/signal... but if the
95 admin is asking for a non-graceful shutdown, how much effort should
96 we put into doing it in a nice way?)
99 - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
100 But the preferred method of handling timeouts is to use the
101 timeouts provided by the BUFF abstraction.
102 - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
103 for any of their own processing, it must be restored to SIG_IGN
104 prior to executing or returning to any apache code.
105 TODO: add SIGPIPE debugging check somewhere to make sure its SIG_IGN
109 * This is the function that MPMs must create. This function is responsible
110 * for controlling the parent and child processes. It will run until a
111 * restart/shutdown is indicated.
112 * @param pconf the configuration pool, reset before the config file is read
113 * @param plog the log pool, reset after the config file is read
114 * @param server_conf the global server config.
115 * @return 1 for shutdown 0 otherwise.
116 * @deffunc int ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf)
118 AP_DECLARE(int) ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf);
121 * predicate indicating if a graceful stop has been requested ...
122 * used by the connection loop
123 * @return 1 if a graceful stop has been requested, 0 otherwise
124 * @deffunc int ap_graceful_stop_signalled*void)
126 AP_DECLARE(int) ap_graceful_stop_signalled(void);
129 * Spawn a process with privileges that another module has requested
130 * @param r The request_rec of the current request
131 * @param newproc The resulting process handle.
132 * @param progname The program to run
133 * @param const_args the arguments to pass to the new program. The first
134 * one should be the program name.
135 * @param env The new environment apr_table_t for the new process. This
136 * should be a list of NULL-terminated strings.
137 * @param attr the procattr we should use to determine how to create the new
139 * @param p The pool to use.
141 AP_DECLARE(apr_status_t) ap_os_create_privileged_process(
142 const request_rec *r,
144 const char *progname,
145 const char * const *args,
146 const char * const *env,
147 apr_procattr_t *attr,
151 #define AP_MPMQ_MAX_DAEMONS 1 /* Max # of daemons */
152 #define AP_MPMQ_IS_THREADED 2 /* MPM can do threading */
153 #define AP_MPMQ_IS_FORKED 3 /* MPM can do forking */
156 * Query a property of the current MPM.
157 * @param query_code One of APM_MPMQ_*
158 * @param result A location to place the result of the query
159 * @return APR_SUCCESS or APR_ENOTIMPL
160 * @deffunc int ap_mpm_query(int query_code, int *result)
162 AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);