ap_mpm.h revision f062ed7bd262a37a909dd77ce5fc23b446818823
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin/* ====================================================================
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * The Apache Software License, Version 1.1
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * Copyright (c) 2000 The Apache Software Foundation. All rights
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * reserved.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * Redistribution and use in source and binary forms, with or without
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * modification, are permitted provided that the following conditions
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * are met:
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * 1. Redistributions of source code must retain the above copyright
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * notice, this list of conditions and the following disclaimer.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * 2. Redistributions in binary form must reproduce the above copyright
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * notice, this list of conditions and the following disclaimer in
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * the documentation and/or other materials provided with the
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * distribution.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * 3. The end-user documentation included with the redistribution,
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * if any, must include the following acknowledgment:
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * "This product includes software developed by the
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * Apache Software Foundation (http://www.apache.org/)."
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * Alternately, this acknowledgment may appear in the software itself,
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * if and wherever such third-party acknowledgments normally appear.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * 4. The names "Apache" and "Apache Software Foundation" must
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * not be used to endorse or promote products derived from this
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * software without prior written permission. For written
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * permission, please contact apache@apache.org.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * 5. Products derived from this software may not be called "Apache",
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * nor may "Apache" appear in their name, without prior written
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * permission of the Apache Software Foundation.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * SUCH DAMAGE.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * ====================================================================
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin *
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * This software consists of voluntary contributions made by many
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * individuals on behalf of the Apache Software Foundation. For more
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * information on the Apache Software Foundation, please see
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin * <http://www.apache.org/>.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin */
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin#ifndef AP_MMN_H
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin#define AP_MMN_H
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin/*
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin The MPM, "multi-processing model" provides an abstraction of the
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin interface with the OS for distributing incoming connections to
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin threads/process for processing. http_main invokes the MPM, and
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin the MPM runs until a shutdown/restart has been indicated.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin The MPM calls out to the apache core via the ap_process_connection
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin function when a connection arrives.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin The MPM may or may not be multithreaded. In the event that it is
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin multithreaded, at any instant it guarantees a 1:1 mapping of threads
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin ap_process_connection invocations.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin Note: In the future it will be possible for ap_process_connection
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin to return to the MPM prior to finishing the entire connection; and
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin the MPM will proceed with asynchronous handling for the connection;
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin in the future the MPM may call ap_process_connection again -- but
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin does not guarantee it will occur on the same thread as the first call.
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin The MPM further guarantees that no asynchronous behaviour such as
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin longjmps and signals will interfere with the user code that is
b45c2b86612fd10c2b08965bb99e66a3c0e43480minfrin invoked through ap_process_connection. The MPM may reserve some
signals for its use (i.e. SIGUSR1), but guarantees that these signals
are ignored when executing outside the MPM code itself. (This
allows broken user code that does not handle EINTR to function
properly.)
The suggested server restart and stop behaviour will be "graceful".
However the MPM may choose to terminate processes when the user
requests a non-graceful restart/stop. When this occurs, the MPM kills
all threads with extreme prejudice, and destroys the pchild pool.
User cleanups registered in the pchild ap_context_t will be invoked at
this point. (This can pose some complications, the user cleanups
are asynchronous behaviour not unlike longjmp/signal... but if the
admin is asking for a non-graceful shutdown, how much effort should
we put into doing it in a nice way?)
unix/posix notes:
- The MPM does not set a SIGALRM handler, user code may use SIGALRM.
But the preferred method of handling timeouts is to use the
timeouts provided by the BUFF/iol abstraction.
- The proper setting for SIGPIPE is SIG_IGN, if user code changes it
for any of their own processing, it must be restored to SIG_IGN
prior to executing or returning to any apache code.
TODO: add SIGPIPE debugging check somewhere to make sure its SIG_IGN
*/
/* run until a restart/shutdown is indicated, return 1 for shutdown
0 otherwise */
API_EXPORT(int) ap_mpm_run(ap_context_t *pconf, ap_context_t *plog, server_rec *server_conf);
/* predicate indicating if a graceful stop has been requested ...
used by the connection loop */
API_EXPORT(int) ap_graceful_stop_signalled(void);
/*
* ap_start_shutdown() and ap_start_restart() are functions to initiate
* shutdown or restart without relying on signals.
*
* These should only be called from the parent process itself, since the
* parent process will use the shutdown_pending and restart_pending variables
* to determine whether to shutdown or restart. The child process should
* call signal_parent() directly to tell the parent to die -- this will
* cause neither of those variable to be set, which the parent will
* assume means something serious is wrong (which it will be, for the
* child to force an exit) and so do an exit anyway.
*/
void ap_start_shutdown(void);
void ap_start_restart(int graceful);
/*
* ap_signal_parent() - used to send a signal to the parent process.
*/
void ap_signal_parent(ap_context_t *p, const char* signal, const char* server_root);
#ifdef HAS_OTHER_CHILD
/*
* register an other_child -- a child which the main loop keeps track of
* and knows it is different than the rest of the scoreboard.
*
* pid is the pid of the child.
*
* maintenance is a function that is invoked with a reason, the data
* pointer passed here, and when appropriate a status result from waitpid().
*
* write_fd is an fd that is probed for writing by select() if it is ever
* unwritable, then maintenance is invoked with reason OC_REASON_UNWRITABLE.
* This is useful for log pipe children, to know when they've blocked. To
* disable this feature, use -1 for write_fd.
*/
API_EXPORT(void) ap_register_other_child(int pid,
void (*maintenance) (int reason, void *data, ap_wait_t status), void *data,
int write_fd);
#define OC_REASON_DEATH 0 /* child has died, caller must call
* unregister still */
#define OC_REASON_UNWRITABLE 1 /* write_fd is unwritable */
#define OC_REASON_RESTART 2 /* a restart is occuring, perform
* any necessary cleanup (including
* sending a special signal to child)
*/
#define OC_REASON_UNREGISTER 3 /* unregister has been called, do
* whatever is necessary (including
* kill the child) */
#define OC_REASON_LOST 4 /* somehow the child exited without
* us knowing ... buggy os? */
/*
* unregister an other_child. Note that the data pointer is used here, and
* is assumed to be unique per other_child. This is because the pid and
* write_fd are possibly killed off separately.
*/
API_EXPORT(void) ap_unregister_other_child(void *data);
#endif
#endif