ap_mpm.h

Go to the documentation of this file.

/* Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#ifndef AP_MPM_H
#define AP_MPM_H
 
#include "apr_thread_proc.h"
#include "httpd.h"
#include "scoreboard.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
/*
    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 it's SIG_IGN
*/
 
AP_DECLARE_HOOK(int, mpm, (apr_pool_t *pconf, apr_pool_t *plog, server_rec *server_conf))
 
 
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_NOT_SUPPORTED      0  
#define AP_MPMQ_STATIC             1  
#define AP_MPMQ_DYNAMIC            2  
#define AP_MPMQ_STARTING              0
#define AP_MPMQ_RUNNING               1
#define AP_MPMQ_STOPPING              2
#define AP_MPMQ_MAX_DAEMON_USED       1
#define AP_MPMQ_IS_THREADED           2
#define AP_MPMQ_IS_FORKED             3
#define AP_MPMQ_HARD_LIMIT_DAEMONS    4
#define AP_MPMQ_HARD_LIMIT_THREADS    5
#define AP_MPMQ_MAX_THREADS           6
#define AP_MPMQ_MIN_SPARE_DAEMONS     7
#define AP_MPMQ_MIN_SPARE_THREADS     8
#define AP_MPMQ_MAX_SPARE_DAEMONS     9
#define AP_MPMQ_MAX_SPARE_THREADS    10
#define AP_MPMQ_MAX_REQUESTS_DAEMON  11
#define AP_MPMQ_MAX_DAEMONS          12
#define AP_MPMQ_MPM_STATE            13
#define AP_MPMQ_IS_ASYNC             14
#define AP_MPMQ_GENERATION           15
#define AP_MPMQ_HAS_SERF             16
#define AP_MPMQ_CAN_SUSPEND          17
#define AP_MPMQ_CAN_POLL             18
AP_DECLARE(apr_status_t) ap_mpm_query(int query_code, int *result);
 
typedef void (ap_mpm_callback_fn_t)(void *baton);
 
/* only added support in the Event MPM....  check for APR_ENOTIMPL */
AP_DECLARE(apr_status_t) ap_mpm_resume_suspended(conn_rec *c);
/* only added support in the Event MPM....  check for APR_ENOTIMPL */
AP_DECLARE(apr_status_t) ap_mpm_register_timed_callback(
        apr_time_t t, ap_mpm_callback_fn_t *cbfn, void *baton);
 
AP_DECLARE(apr_status_t) ap_mpm_register_poll_callback(
        apr_pool_t *p, const apr_array_header_t *pfds,
        ap_mpm_callback_fn_t *cbfn, void *baton);
 
AP_DECLARE(apr_status_t) ap_mpm_register_poll_callback_timeout(
        apr_pool_t *p, const apr_array_header_t *pfds,
        ap_mpm_callback_fn_t *cbfn, ap_mpm_callback_fn_t *tofn,
        void *baton, apr_time_t timeout);
 
 
typedef enum mpm_child_status {
    MPM_CHILD_STARTED,
    MPM_CHILD_EXITED,
    MPM_CHILD_LOST_SLOT
} mpm_child_status;
 
AP_DECLARE_HOOK(void,child_status,(server_rec *s, pid_t pid, ap_generation_t gen,
                                   int slot, mpm_child_status state))
 
 
AP_DECLARE_HOOK(void,end_generation,(server_rec *s, ap_generation_t gen))
 
/* Defining GPROF when compiling uses the moncontrol() function to
 * disable gprof profiling in the parent, and enable it only for
 * request processing in children (or in one_process mode).  It's
 * absolutely required to get useful gprof results under linux
 * because the profile itimers and such are disabled across a
 * fork().  It's probably useful elsewhere as well.
 */
#ifdef GPROF
extern void moncontrol(int);
#define AP_MONCONTROL(x) moncontrol(x)
#else
#define AP_MONCONTROL(x)
#endif
 
#ifdef AP_ENABLE_EXCEPTION_HOOK
typedef struct ap_exception_info_t {
    int sig;
    pid_t pid;
} ap_exception_info_t;
 
AP_DECLARE_HOOK(int,fatal_exception,(ap_exception_info_t *ei))
#endif /*AP_ENABLE_EXCEPTION_HOOK*/
 
#ifdef __cplusplus
}
#endif
 
#endif