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

   1 /* ====================================================================
   2  * Copyright (c) 1995-1999 The Apache Group.  All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  *
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  *
  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
  14  *    distribution.
  15  *
  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/)."
  20  *
  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
  24  *    apache@apache.org.
  25  *
  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.
  29  *
  30  * 6. Redistributions of any form whatsoever must retain the following
  31  *    acknowledgment:
  32  *    "This product includes software developed by the Apache Group
  33  *    for use in the Apache HTTP server project (http://www.apache.org/)."
  34  *
  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  * ====================================================================
  48  *
  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/>.
  55  *
  56  */
  57
  58 #ifndef AP_MMN_H
  59 #define AP_MMN_H
  60
  61 /*
  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.
  68
  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.  The only primitives the MPM
  72     provides for synchronization between threads are the ap_thread_mutex
  73     stuff below.
  74
  75     Note: In the future it will be possible for ap_process_connection
  76     to return to the MPM prior to finishing the entire connection; and
  77     the MPM will proceed with asynchronous handling for the connection;
  78     in the future the MPM may call ap_process_connection again -- but
  79     does not guarantee it will occur on the same thread as the first call.
  80
  81     The MPM further guarantees that no asynchronous behaviour such as
  82     longjmps and signals will interfere with the user code that is
  83     invoked through ap_process_connection.  The MPM may reserve some
  84     signals for its use (i.e. SIGUSR1), but guarantees that these signals
  85     are ignored when executing outside the MPM code itself.  (This
  86     allows broken user code that does not handle EINTR to function
  87     properly.)
  88
  89     The suggested server restart and stop behaviour will be "graceful".
  90     However the MPM may choose to terminate processes when the user
  91     requests a non-graceful restart/stop.  When this occurs, the MPM kills
  92     all threads with extreme prejudice, and destroys the pchild pool.
  93     User cleanups registered in the pchild pool will be invoked at
  94     this point.  (This can pose some complications, the user cleanups
  95     are asynchronous behaviour not unlike longjmp/signal... but if the
  96     admin is asking for a non-graceful shutdown, how much effort should
  97     we put into doing it in a nice way?)
  98
  99     unix/posix notes:
 100     - The MPM does not set a SIGALRM handler, user code may use SIGALRM.
 101         But the preferred method of handling timeouts is to use the
 102         timeouts provided by the BUFF/iol abstraction.
 103     - The proper setting for SIGPIPE is SIG_IGN, if user code changes it
 104         for any of their own processing, it must be restored to SIG_IGN
 105         prior to executing or returning to any apache code.
 106     TODO: add SIGPIPE debugging check somewhere to make sure its SIG_IGN
 107 */
 108
 109 /* run until a restart/shutdown is indicated, return 1 for shutdown
 110    0 otherwise */
 111 API_EXPORT(int) ap_mpm_run(pool *pconf, pool *plog, server_rec *server_conf);
 112
 113 /* predicate indicating if a graceful stop has been requested ...
 114    used by the connection loop */
 115 API_EXPORT(int) ap_graceful_stop_signalled(void);
 116
 117 /* a mutex which synchronizes threads within one process */
 118 typedef struct ap_thread_mutex ap_thread_mutex;
 119 API_EXPORT(ap_thread_mutex *) ap_thread_mutex_new(void);
 120 API_EXPORT(void) ap_thread_mutex_lock(ap_thread_mutex *);
 121 API_EXPORT(void) ap_thread_mutex_unlock(ap_thread_mutex *);
 122 API_EXPORT(void) ap_thread_mutex_destroy(ap_thread_mutex *);
 123
 124 #ifdef HAS_OTHER_CHILD
 125 /*
 126  * register an other_child -- a child which the main loop keeps track of
 127  * and knows it is different than the rest of the scoreboard.
 128  *
 129  * pid is the pid of the child.
 130  *
 131  * maintenance is a function that is invoked with a reason, the data
 132  * pointer passed here, and when appropriate a status result from waitpid().
 133  *
 134  * write_fd is an fd that is probed for writing by select() if it is ever
 135  * unwritable, then maintenance is invoked with reason OC_REASON_UNWRITABLE.
 136  * This is useful for log pipe children, to know when they've blocked.  To
 137  * disable this feature, use -1 for write_fd.
 138  */
 139 API_EXPORT(void) ap_register_other_child(int pid,
 140        void (*maintenance) (int reason, void *data, ap_wait_t status), void *data,
 141                                       int write_fd);
 142 #define OC_REASON_DEATH         0       /* child has died, caller must call
 143                                          * unregister still */
 144 #define OC_REASON_UNWRITABLE    1       /* write_fd is unwritable */
 145 #define OC_REASON_RESTART       2       /* a restart is occuring, perform
 146                                          * any necessary cleanup (including
 147                                          * sending a special signal to child)
 148                                          */
 149 #define OC_REASON_UNREGISTER    3       /* unregister has been called, do
 150                                          * whatever is necessary (including
 151                                          * kill the child) */
 152 #define OC_REASON_LOST          4       /* somehow the child exited without
 153                                          * us knowing ... buggy os? */
 154
 155 /*
 156  * unregister an other_child.  Note that the data pointer is used here, and
 157  * is assumed to be unique per other_child.  This is because the pid and
 158  * write_fd are possibly killed off separately.
 159  */
 160 API_EXPORT(void) ap_unregister_other_child(void *data);
 161
 162 #endif
 163
 164 #endif