granicus.if.org Git - apache/blob - include/ap_mpm.h

   1 /* ====================================================================
   2  * The Apache Software License, Version 1.1
   3  *
   4  * Copyright (c) 2000 The Apache Software Foundation.  All rights
   5  * reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without
   8  * modification, are permitted provided that the following conditions
   9  * are met:
  10  *
  11  * 1. Redistributions of source code must retain the above copyright
  12  *    notice, this list of conditions and the following disclaimer.
  13  *
  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
  17  *    distribution.
  18  *
  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.
  25  *
  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.
  30  *
  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.
  34  *
  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
  46  * SUCH DAMAGE.
  47  * ====================================================================
  48  *
  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/>.
  53  */
  54
  55 #ifndef AP_MMN_H
  56 #define AP_MMN_H
  57
  58 /*
  59     The MPM, "multi-processing model" provides an abstraction of the
  60     interface with the OS for distributing incoming connections to
  61     threads/process for processing.  http_main invokes the MPM, and
  62     the MPM runs until a shutdown/restart has been indicated.
  63     The MPM calls out to the apache core via the ap_process_connection
  64     function when a connection arrives.
  65
  66     The MPM may or may not be multithreaded.  In the event that it is
  67     multithreaded, at any instant it guarantees a 1:1 mapping of threads
  68     ap_process_connection invocations.
  69
  70     Note: In the future it will be possible for ap_process_connection
  71     to return to the MPM prior to finishing the entire connection; and
  72     the MPM will proceed with asynchronous handling for the connection;
  73     in the future the MPM may call ap_process_connection again -- but
  74     does not guarantee it will occur on the same thread as the first call.
  75
  76     The MPM further guarantees that no asynchronous behaviour such as
  77     longjmps and signals will interfere with the user code that is
  78     invoked through ap_process_connection.  The MPM may reserve some
  79     signals for its use (i.e. SIGUSR1), but guarantees that these signals
  80     are ignored when executing outside the MPM code itself.  (This
  81     allows broken user code that does not handle EINTR to function
  82     properly.)
  83
  84     The suggested server restart and stop behaviour will be "graceful".
  85     However the MPM may choose to terminate processes when the user
  86     requests a non-graceful restart/stop.  When this occurs, the MPM kills
  87     all threads with extreme prejudice, and destroys the pchild pool.
  88     User cleanups registered in the pchild ap_pool_t will be invoked at
  89     this point.  (This can pose some complications, the user cleanups
  90     are asynchronous behaviour not unlike longjmp/signal... but if the
  91     admin is asking for a non-graceful shutdown, how much effort should
  92     we put into doing it in a nice way?)
  93
  94     unix/posix notes:
  95     - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
  96         But the preferred method of handling timeouts is to use the
  97         timeouts provided by the BUFF/iol abstraction.
  98     - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
  99         for any of their own processing, it must be restored to SIG_IGN
 100         prior to executing or returning to any apache code.
 101     TODO: add SIGPIPE debugging check somewhere to make sure its SIG_IGN
 102 */
 103
 104 /* run until a restart/shutdown is indicated, return 1 for shutdown
 105    0 otherwise */
 106 API_EXPORT(int) ap_mpm_run(ap_pool_t *pconf, ap_pool_t *plog, server_rec *server_conf);
 107
 108 /* predicate indicating if a graceful stop has been requested ...
 109    used by the connection loop */
 110 API_EXPORT(int) ap_graceful_stop_signalled(void);
 111
 112 /*
 113  * ap_start_shutdown() and ap_start_restart() are functions to initiate
 114  * shutdown or restart without relying on signals.
 115  *
 116  * These should only be called from the parent process itself, since the
 117  * parent process will use the shutdown_pending and restart_pending variables
 118  * to determine whether to shutdown or restart. The child process should
 119  * call signal_parent() directly to tell the parent to die -- this will
 120  * cause neither of those variable to be set, which the parent will
 121  * assume means something serious is wrong (which it will be, for the
 122  * child to force an exit) and so do an exit anyway.
 123  */
 124
 125 void ap_start_shutdown(void);
 126 void ap_start_restart(int graceful);
 127
 128 /*
 129  * ap_signal_parent() - used to send a signal to the parent process.
 130  */
 131 void ap_signal_parent(ap_pool_t *p, const char* signal, const char* server_root);
 132
 133 #endif