ap_mpm.h revision f44d73842e45390adaecf468eb99d6654e29c33d
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek/* ====================================================================
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * The Apache Software License, Version 1.1
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * Copyright (c) 2000-2001 The Apache Software Foundation. All rights
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * reserved.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * Redistribution and use in source and binary forms, with or without
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * modification, are permitted provided that the following conditions
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * are met:
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * 1. Redistributions of source code must retain the above copyright
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * notice, this list of conditions and the following disclaimer.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * 2. Redistributions in binary form must reproduce the above copyright
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * notice, this list of conditions and the following disclaimer in
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * the documentation and/or other materials provided with the
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * distribution.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * 3. The end-user documentation included with the redistribution,
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * if any, must include the following acknowledgment:
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * "This product includes software developed by the
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * Apache Software Foundation (http://www.apache.org/)."
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * Alternately, this acknowledgment may appear in the software itself,
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * if and wherever such third-party acknowledgments normally appear.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * 4. The names "Apache" and "Apache Software Foundation" must
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * not be used to endorse or promote products derived from this
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * software without prior written permission. For written
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * permission, please contact apache@apache.org.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * 5. Products derived from this software may not be called "Apache",
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * nor may "Apache" appear in their name, without prior written
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * permission of the Apache Software Foundation.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * SUCH DAMAGE.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * ====================================================================
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek *
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * This software consists of voluntary contributions made by many
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * individuals on behalf of the Apache Software Foundation. For more
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * information on the Apache Software Foundation, please see
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * <http://www.apache.org/>.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek */
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek#ifndef AP_MMN_H
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek#define AP_MMN_H
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek/**
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek * @package Multi-Processing Module library
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek */
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek/*
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek The MPM, "multi-processing model" provides an abstraction of the
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek interface with the OS for distributing incoming connections to
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek threads/process for processing. http_main invokes the MPM, and
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek the MPM runs until a shutdown/restart has been indicated.
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek The MPM calls out to the apache core via the ap_process_connection
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek function when a connection arrives.
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek The MPM may or may not be multithreaded. In the event that it is
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek multithreaded, at any instant it guarantees a 1:1 mapping of threads
f47ad59316ddbfce0b24edac752222d300ed0da4Zbigniew Jędrzejewski-Szmek ap_process_connection invocations.
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek Note: In the future it will be possible for ap_process_connection
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek to return to the MPM prior to finishing the entire connection; and
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek the MPM will proceed with asynchronous handling for the connection;
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek in the future the MPM may call ap_process_connection again -- but
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek does not guarantee it will occur on the same thread as the first call.
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek The MPM further guarantees that no asynchronous behaviour such as
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek longjmps and signals will interfere with the user code that is
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek invoked through ap_process_connection. The MPM may reserve some
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek signals for its use (i.e. SIGUSR1), but guarantees that these signals
203af57fcdced5debfc26e1083eaefa031e322f4Zbigniew Jędrzejewski-Szmek are ignored when executing outside the MPM code itself. (This
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek allows broken user code that does not handle EINTR to function
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek properly.)
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek The suggested server restart and stop behaviour will be "graceful".
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek However the MPM may choose to terminate processes when the user
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek requests a non-graceful restart/stop. When this occurs, the MPM kills
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek all threads with extreme prejudice, and destroys the pchild pool.
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek User cleanups registered in the pchild apr_pool_t will be invoked at
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek this point. (This can pose some complications, the user cleanups
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek are asynchronous behaviour not unlike longjmp/signal... but if the
6fc5a40438dee0972cf1dedca9d4fd1c257c8f91Zbigniew Jędrzejewski-Szmek 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);
/* Subtypes/Values for AP_MPMQ_IS_THREADED and AP_MPMQ_IS_FORKED */
#define AP_MPMQ_NOT_SUPPORTED 0 /* This value specifies whether */
/* an MPM is capable of */
/* threading or forking. */
#define AP_MPMQ_STATIC 1 /* This value specifies whether */
/* an MPM is using a static # */
/* threads or daemons. */
#define AP_MPMQ_DYNAMIC 2 /* This value specifies whether */
/* an MPM is using a dynamic # */
/* threads or daemons. */
#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 */
#define AP_MPMQ_HARD_LIMIT_DAEMONS 4 /* The compiled max # deamons */
#define AP_MPMQ_HARD_LIMIT_THREADS 5 /* The compiled max # threads */
#define AP_MPMQ_MAX_THREADS 6 /* Max # of threads */
#define AP_MPMQ_MIN_SPARE_DEAMONS 7 /* Min # of spare daemons */
#define AP_MPMQ_MIN_SPARE_THREADS 8 /* Min # of spare threads */
#define AP_MPMQ_MAX_SPARE_DAEMONS 9 /* Max # of spare daemons */
#define AP_MPMQ_MAX_SPARE_THREADS 10 /* Max # of spare threads */
#define AP_MPMQ_MAX_REQUESTS_DEAMON 11 /* Max # of requests per daemon */
/**
* 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