| /* ==================================================================== |
| * The Apache Software License, Version 1.1 |
| * |
| * Copyright (c) 2000-2001 The Apache Software Foundation. All rights |
| * reserved. |
| * |
| * Redistribution and use in source and binary forms, with or without |
| * modification, are permitted provided that the following conditions |
| * are met: |
| * |
| * 1. Redistributions of source code must retain the above copyright |
| * notice, this list of conditions and the following disclaimer. |
| * |
| * 2. Redistributions in binary form must reproduce the above copyright |
| * notice, this list of conditions and the following disclaimer in |
| * the documentation and/or other materials provided with the |
| * distribution. |
| * |
| * 3. The end-user documentation included with the redistribution, |
| * if any, must include the following acknowledgment: |
| * "This product includes software developed by the |
| * Apache Software Foundation (http://www.apache.org/)." |
| * Alternately, this acknowledgment may appear in the software itself, |
| * if and wherever such third-party acknowledgments normally appear. |
| * |
| * 4. The names "Apache" and "Apache Software Foundation" must |
| * not be used to endorse or promote products derived from this |
| * software without prior written permission. For written |
| * permission, please contact apache@apache.org. |
| * |
| * 5. Products derived from this software may not be called "Apache", |
| * nor may "Apache" appear in their name, without prior written |
| * permission of the Apache Software Foundation. |
| * |
| * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED |
| * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES |
| * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE |
| * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR |
| * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
| * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
| * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF |
| * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND |
| * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, |
| * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT |
| * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| * SUCH DAMAGE. |
| * ==================================================================== |
| * |
| * This software consists of voluntary contributions made by many |
| * individuals on behalf of the Apache Software Foundation. For more |
| * information on the Apache Software Foundation, please see |
| * <http://www.apache.org/>. |
| */ |
| |
| #ifndef AP_MMN_H |
| #define AP_MMN_H |
| |
| /** |
| * @package Multi-Processing Module library |
| */ |
| |
| /* |
| The MPM, "multi-processing model" provides an abstraction of the |
| interface with the OS for distributing incoming connections to |
| threads/process for processing. http_main invokes the MPM, and |
| the MPM runs until a shutdown/restart has been indicated. |
| The MPM calls out to the apache core via the ap_process_connection |
| function when a connection arrives. |
| |
| The MPM may or may not be multithreaded. In the event that it is |
| multithreaded, at any instant it guarantees a 1:1 mapping of threads |
| ap_process_connection invocations. |
| |
| Note: In the future it will be possible for ap_process_connection |
| to return to the MPM prior to finishing the entire connection; and |
| the MPM will proceed with asynchronous handling for the connection; |
| in the future the MPM may call ap_process_connection again -- but |
| does not guarantee it will occur on the same thread as the first call. |
| |
| The MPM further guarantees that no asynchronous behaviour such as |
| longjmps and signals will interfere with the user code that is |
| 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 apr_pool_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 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 |
| */ |
| |
| /** |
| * This is the function that MPMs must create. This function is responsible |
| * for controlling the parent and child processes. It will run until a |
| * restart/shutdown is indicated. |
| * @param pconf the configuration pool, reset before the config file is read |
| * @param plog the log pool, reset after the config file is read |
| * @param server_conf the global server config. |
| * @return 1 for shutdown 0 otherwise. |
| * @deffunc int ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf) |
| */ |
| AP_DECLARE(int) ap_mpm_run(apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf); |
| |
| /** |
| * predicate indicating if a graceful stop has been requested ... |
| * used by the connection loop |
| * @return 1 if a graceful stop has been requested, 0 otherwise |
| * @deffunc int ap_graceful_stop_signalled*void) |
| */ |
| AP_DECLARE(int) ap_graceful_stop_signalled(void); |
| |
| /** |
| * Spawn a process with privileges that another module has requested |
| * @param r The request_rec of the current request |
| * @param newproc The resulting process handle. |
| * @param progname The program to run |
| * @param const_args the arguments to pass to the new program. The first |
| * one should be the program name. |
| * @param env The new environment apr_table_t for the new process. This |
| * should be a list of NULL-terminated strings. |
| * @param attr the procattr we should use to determine how to create the new |
| * process |
| * @param p The pool to use. |
| */ |
| AP_DECLARE(apr_status_t) ap_os_create_privileged_process( |
| const request_rec *r, |
| apr_proc_t *newproc, |
| const char *progname, |
| const char * const *args, |
| const char * const *env, |
| apr_procattr_t *attr, |
| apr_pool_t *p); |
| |
| |
| #define AP_MPMQ_MAX_DAEMONS 1 /* Max # of daemons */ |
| #define AP_MPMQ_IS_THREADED 2 /* MPM can do threading */ |
| #define AP_MPMQ_IS_FORKED 3 /* MPM can do forking */ |
| |
| /** |
| * Query a property of the current MPM. |
| * @param query_code One of APM_MPMQ_* |
| * @param result A location to place the result of the query |
| * @return APR_SUCCESS or APR_ENOTIMPL |
| * @deffunc int ap_mpm_query(int query_code, int *result) |
| */ |
| AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result); |
| |
| #endif |