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