1 /* ====================================================================
2 * Copyright (c) 1995-1999 The Apache Group. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
16 * 3. All advertising materials mentioning features or use of this
17 * software must display the following acknowledgment:
18 * "This product includes software developed by the Apache Group
19 * for use in the Apache HTTP server project (http://www.apache.org/)."
21 * 4. The names "Apache Server" and "Apache Group" must not be used to
22 * endorse or promote products derived from this software without
23 * prior written permission. For written permission, please contact
26 * 5. Products derived from this software may not be called "Apache"
27 * nor may "Apache" appear in their names without prior written
28 * permission of the Apache Group.
30 * 6. Redistributions of any form whatsoever must retain the following
32 * "This product includes software developed by the Apache Group
33 * for use in the Apache HTTP server project (http://www.apache.org/)."
35 * THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
36 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
37 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
38 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
41 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
42 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
43 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
44 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
45 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
46 * OF THE POSSIBILITY OF SUCH DAMAGE.
47 * ====================================================================
49 * This software consists of voluntary contributions made by many
50 * individuals on behalf of the Apache Group and was originally based
51 * on public domain software written at the National Center for
52 * Supercomputing Applications, University of Illinois, Urbana-Champaign.
53 * For more information on the Apache Group and the Apache HTTP server
54 * project, please see <http://www.apache.org/>.
62 The MPM, "multi-processing model" provides an abstraction of the
63 interface with the OS for distributing incoming connections to
64 threads/process for processing. http_main invokes the MPM, and
65 the MPM runs until a shutdown/restart has been indicated.
66 The MPM calls out to the apache core via the ap_process_connection
67 function when a connection arrives.
69 The MPM may or may not be multithreaded. In the event that it is
70 multithreaded, at any instant it guarantees a 1:1 mapping of threads
71 ap_process_connection invocations.
73 Note: In the future it will be possible for ap_process_connection
74 to return to the MPM prior to finishing the entire connection; and
75 the MPM will proceed with asynchronous handling for the connection;
76 in the future the MPM may call ap_process_connection again -- but
77 does not guarantee it will occur on the same thread as the first call.
79 The MPM further guarantees that no asynchronous behaviour such as
80 longjmps and signals will interfere with the user code that is
81 invoked through ap_process_connection. The MPM may reserve some
82 signals for its use (i.e. SIGUSR1), but guarantees that these signals
83 are ignored when executing outside the MPM code itself. (This
84 allows broken user code that does not handle EINTR to function
87 The suggested server restart and stop behaviour will be "graceful".
88 However the MPM may choose to terminate processes when the user
89 requests a non-graceful restart/stop. When this occurs, the MPM kills
90 all threads with extreme prejudice, and destroys the pchild pool.
91 User cleanups registered in the pchild ap_context_t will be invoked at
92 this point. (This can pose some complications, the user cleanups
93 are asynchronous behaviour not unlike longjmp/signal... but if the
94 admin is asking for a non-graceful shutdown, how much effort should
95 we put into doing it in a nice way?)
98 - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
99 But the preferred method of handling timeouts is to use the
100 timeouts provided by the BUFF/iol abstraction.
101 - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
102 for any of their own processing, it must be restored to SIG_IGN
103 prior to executing or returning to any apache code.
104 TODO: add SIGPIPE debugging check somewhere to make sure its SIG_IGN
107 /* run until a restart/shutdown is indicated, return 1 for shutdown
109 API_EXPORT(int) ap_mpm_run(ap_context_t *pconf, ap_context_t *plog, server_rec *server_conf);
111 /* predicate indicating if a graceful stop has been requested ...
112 used by the connection loop */
113 API_EXPORT(int) ap_graceful_stop_signalled(void);
116 * ap_start_shutdown() and ap_start_restart() are functions to initiate
117 * shutdown or restart without relying on signals.
119 * These should only be called from the parent process itself, since the
120 * parent process will use the shutdown_pending and restart_pending variables
121 * to determine whether to shutdown or restart. The child process should
122 * call signal_parent() directly to tell the parent to die -- this will
123 * cause neither of those variable to be set, which the parent will
124 * assume means something serious is wrong (which it will be, for the
125 * child to force an exit) and so do an exit anyway.
128 void ap_start_shutdown(void);
129 void ap_start_restart(int graceful);
132 * ap_signal_parent() - used to send a signal to the parent process.
134 void ap_signal_parent(ap_context_t *p, const char* signal, const char* server_root);
136 #ifdef HAS_OTHER_CHILD
138 * register an other_child -- a child which the main loop keeps track of
139 * and knows it is different than the rest of the scoreboard.
141 * pid is the pid of the child.
143 * maintenance is a function that is invoked with a reason, the data
144 * pointer passed here, and when appropriate a status result from waitpid().
146 * write_fd is an fd that is probed for writing by select() if it is ever
147 * unwritable, then maintenance is invoked with reason OC_REASON_UNWRITABLE.
148 * This is useful for log pipe children, to know when they've blocked. To
149 * disable this feature, use -1 for write_fd.
151 API_EXPORT(void) ap_register_other_child(int pid,
152 void (*maintenance) (int reason, void *data, ap_wait_t status), void *data,
154 #define OC_REASON_DEATH 0 /* child has died, caller must call
155 * unregister still */
156 #define OC_REASON_UNWRITABLE 1 /* write_fd is unwritable */
157 #define OC_REASON_RESTART 2 /* a restart is occuring, perform
158 * any necessary cleanup (including
159 * sending a special signal to child)
161 #define OC_REASON_UNREGISTER 3 /* unregister has been called, do
162 * whatever is necessary (including
164 #define OC_REASON_LOST 4 /* somehow the child exited without
165 * us knowing ... buggy os? */
168 * unregister an other_child. Note that the data pointer is used here, and
169 * is assumed to be unique per other_child. This is because the pid and
170 * write_fd are possibly killed off separately.
172 API_EXPORT(void) ap_unregister_other_child(void *data);