Multi-Processing Modules

Collaboration diagram for Multi-Processing Modules:

Data Structures
struct	ap_pod_t

Macros
#define	DEFAULT_LISTENBACKLOG   511
#define	AP_SIG_GRACEFUL   SIGUSR1
#define	AP_SIG_GRACEFUL_SHORT   USR1
#define	AP_SIG_GRACEFUL_STRING   "SIGUSR1"
#define	AP_SIG_GRACEFUL_STOP   SIGWINCH
#define	AP_SIG_GRACEFUL_STOP_SHORT   WINCH
#define	AP_SIG_GRACEFUL_STOP_STRING   "SIGWINCH"
#define	ap_sock_disable_nagle(s)   /* NOOP */
#define	AP_MPM_PODX_RESTART_CHAR   '$'
#define	AP_MPM_PODX_GRACEFUL_CHAR   '!'
#define	AP_GRACEFUL_SHUTDOWN_TIMEOUT_COMMAND
#define	AP_ACCEPT_MUTEX_TYPE   "mpm-accept"

Typedefs
typedef void	ap_reclaim_callback_fn_t(int childnum, pid_t pid, ap_generation_t gen)
typedef struct ap_pod_t	ap_pod_t

Enumerations
enum	ap_podx_restart_t { AP_MPM_PODX_NORESTART , AP_MPM_PODX_RESTART , AP_MPM_PODX_GRACEFUL }

Functions
void	ap_reclaim_child_processes (int terminate, ap_reclaim_callback_fn_t *mpm_callback)
void	ap_relieve_child_processes (ap_reclaim_callback_fn_t *mpm_callback)
void	ap_register_extra_mpm_process (pid_t pid, ap_generation_t gen)
int	ap_unregister_extra_mpm_process (pid_t pid, ap_generation_t *old_gen)
apr_status_t	ap_mpm_safe_kill (pid_t pid, int sig)
int	ap_process_child_status (apr_proc_t *pid, apr_exit_why_e why, int status)
apr_status_t	ap_fatal_signal_setup (server_rec *s, apr_pool_t *in_pconf)
apr_status_t	ap_fatal_signal_child_setup (server_rec *s)
apr_status_t	ap_mpm_end_gen_helper (void *unused)
void	ap_wait_or_timeout (apr_exit_why_e *status, int *exitcode, apr_proc_t *ret, apr_pool_t *p, server_rec *s)
uid_t	ap_uname2id (const char *name)
gid_t	ap_gname2id (const char *name)
apr_status_t	ap_mpm_pod_open (apr_pool_t *p, ap_pod_t **pod)
apr_status_t	ap_mpm_pod_check (ap_pod_t *pod)
apr_status_t	ap_mpm_pod_close (ap_pod_t *pod)
apr_status_t	ap_mpm_pod_signal (ap_pod_t *pod)
void	ap_mpm_pod_killpg (ap_pod_t *pod, int num)
apr_status_t	ap_mpm_podx_open (apr_pool_t *p, ap_pod_t **pod)
int	ap_mpm_podx_check (ap_pod_t *pod)
apr_status_t	ap_mpm_podx_close (ap_pod_t *pod)
apr_status_t	ap_mpm_podx_signal (ap_pod_t *pod, ap_podx_restart_t graceful)
void	ap_mpm_podx_killpg (ap_pod_t *pod, int num, ap_podx_restart_t graceful)
const char *	ap_check_mpm (void)
const char *	ap_mpm_set_max_requests (cmd_parms *cmd, void *dummy, const char *arg)
const char *	ap_mpm_set_pidfile (cmd_parms *cmd, void *dummy, const char *arg)
void	ap_mpm_dump_pidfile (apr_pool_t *p, apr_file_t *out)
const char *	ap_mpm_set_coredumpdir (cmd_parms *cmd, void *dummy, const char *arg)
const char *	ap_mpm_set_graceful_shutdown (cmd_parms *cmd, void *dummy, const char *arg)
int	ap_signal_server (int *, apr_pool_t *)
void	ap_mpm_rewrite_args (process_rec *)
const char *	ap_mpm_set_max_mem_free (cmd_parms *cmd, void *dummy, const char *arg)
const char *	ap_mpm_set_thread_stacksize (cmd_parms *cmd, void *dummy, const char *arg)
void	ap_core_child_status (server_rec *s, pid_t pid, ap_generation_t gen, int slot, mpm_child_status status)
int	ap_sys_privileges_handlers (int inc)
int	drop_privileges (apr_pool_t *pchild, server_rec *s)
apr_status_t	mpm_register_poll_callback_timeout (apr_pool_t *p, const apr_array_header_t *pds, ap_mpm_callback_fn_t *cbfn, ap_mpm_callback_fn_t *tofn, void *baton, apr_time_t timeout)
void	child_stopping (apr_pool_t *pchild, int graceful)
void	child_stopped (apr_pool_t *pchild, int graceful)
void	mpm_common_pre_config (apr_pool_t *pconf)

Variables
AP_DECLARE_DATA int	ap_max_requests_per_child
AP_DECLARE_DATA const char *	ap_pid_fname
AP_DECLARE_DATA char	ap_coredump_dir [MAX_STRING_LEN]
AP_DECLARE_DATA int	ap_coredumpdir_configured
AP_DECLARE_DATA int	ap_graceful_shutdown_timeout
AP_DECLARE_DATA apr_uint32_t	ap_max_mem_free
AP_DECLARE_DATA apr_size_t	ap_thread_stacksize

Detailed Description

Macro Definition Documentation

AP_ACCEPT_MUTEX_TYPE

#define AP_ACCEPT_MUTEX_TYPE   "mpm-accept"

AP_GRACEFUL_SHUTDOWN_TIMEOUT_COMMAND

#define AP_GRACEFUL_SHUTDOWN_TIMEOUT_COMMAND

Value:

AP_INIT_TAKE1("GracefulShutdownTimeout", ap_mpm_set_graceful_shutdown, NULL, \
              RSRC_CONF, "Maximum time in seconds to wait for child "        \
              "processes to complete transactions during shutdown")

AP_MPM_PODX_GRACEFUL_CHAR

#define AP_MPM_PODX_GRACEFUL_CHAR   '!'

AP_MPM_PODX_RESTART_CHAR

#define AP_MPM_PODX_RESTART_CHAR   '$'

AP_SIG_GRACEFUL

#define AP_SIG_GRACEFUL   SIGUSR1

AP_SIG_GRACEFUL_SHORT

#define AP_SIG_GRACEFUL_SHORT   USR1

AP_SIG_GRACEFUL_STOP

#define AP_SIG_GRACEFUL_STOP   SIGWINCH

AP_SIG_GRACEFUL_STOP_SHORT

#define AP_SIG_GRACEFUL_STOP_SHORT   WINCH

AP_SIG_GRACEFUL_STOP_STRING

#define AP_SIG_GRACEFUL_STOP_STRING   "SIGWINCH"

AP_SIG_GRACEFUL_STRING

#define AP_SIG_GRACEFUL_STRING   "SIGUSR1"

ap_sock_disable_nagle

#define ap_sock_disable_nagle

(

s

)

/* NOOP */

DEFAULT_LISTENBACKLOG

#define DEFAULT_LISTENBACKLOG   511

Typedef Documentation

ap_pod_t

typedef struct ap_pod_t ap_pod_t

ap_reclaim_callback_fn_t

typedef void ap_reclaim_callback_fn_t(int childnum, pid_t pid, ap_generation_t gen)

Callback function used for ap_reclaim_child_processes() and ap_relieve_child_processes(). The callback function will be called for each terminated child process.

Enumeration Type Documentation

ap_podx_restart_t

enum ap_podx_restart_t

Enumerator
AP_MPM_PODX_NORESTART
AP_MPM_PODX_RESTART
AP_MPM_PODX_GRACEFUL

Function Documentation

ap_check_mpm()

const char* ap_check_mpm

(

void

)

Check that exactly one MPM is loaded Returns NULL if yes, error string if not.

ap_core_child_status()

void ap_core_child_status	(	server_rec *	s,
		pid_t	pid,
		ap_generation_t	gen,
		int	slot,
		mpm_child_status	status
	)

ap_fatal_signal_child_setup()

apr_status_t ap_fatal_signal_child_setup

(

server_rec *

s

)

ap_fatal_signal_setup()

apr_status_t ap_fatal_signal_setup	(	server_rec *	s,
		apr_pool_t *	in_pconf
	)

ap_gname2id()

gid_t ap_gname2id

(

const char *

name

)

Convert a group name to a numeric ID

Parameters

name	The name to convert

Returns

The group id corresponding to a name

ap_mpm_dump_pidfile()

void ap_mpm_dump_pidfile	(	apr_pool_t *	p,
		apr_file_t *	out
	)

ap_mpm_end_gen_helper()

apr_status_t ap_mpm_end_gen_helper

(

void *

unused

)

Pool cleanup for end-generation hook implementation (core httpd function)

ap_mpm_pod_check()

apr_status_t ap_mpm_pod_check

(

ap_pod_t *

pod

)

Check the pipe to determine if the process has been signalled to die.

ap_mpm_pod_close()

apr_status_t ap_mpm_pod_close

(

ap_pod_t *

pod

)

Close the pipe-of-death

Parameters

pod	the pipe-of-death to close.

ap_mpm_pod_killpg()

void ap_mpm_pod_killpg	(	ap_pod_t *	pod,
		int	num
	)

Write data to the pipe-of-death, signalling that all child process should die.

Parameters

pod	The pipe-of-death to write to.
num	The number of child processes to kill

ap_mpm_pod_open()

apr_status_t ap_mpm_pod_open	(	apr_pool_t *	p,
		ap_pod_t **	pod
	)

Open the pipe-of-death. The pipe of death is used to tell all child processes that it is time to die gracefully.

Parameters

p	The pool to use for allocating the pipe
pod	the pipe-of-death that is created.

ap_mpm_pod_signal()

apr_status_t ap_mpm_pod_signal

(

ap_pod_t *

pod

)

Write data to the pipe-of-death, signalling that one child process should die.

Parameters

pod	the pipe-of-death to write to.

ap_mpm_podx_check()

int ap_mpm_podx_check

(

ap_pod_t *

pod

)

Check the extended pipe to determine if the process has been signalled to die.

ap_mpm_podx_close()

apr_status_t ap_mpm_podx_close

(

ap_pod_t *

pod

)

Close the pipe-of-death

Parameters

pod	The pipe-of-death to close.

ap_mpm_podx_killpg()

void ap_mpm_podx_killpg	(	ap_pod_t *	pod,
		int	num,
		ap_podx_restart_t	graceful
	)

Write data to the extended pipe-of-death, signalling that all child process should die.

Parameters

pod	The pipe-of-death to write to.
num	The number of child processes to kill
graceful	restart-type

ap_mpm_podx_open()

apr_status_t ap_mpm_podx_open	(	apr_pool_t *	p,
		ap_pod_t **	pod
	)

Open the extended pipe-of-death.

Parameters

p	The pool to use for allocating the pipe
pod	The pipe-of-death that is created.

ap_mpm_podx_signal()

apr_status_t ap_mpm_podx_signal	(	ap_pod_t *	pod,
		ap_podx_restart_t	graceful
	)

Write data to the extended pipe-of-death, signalling that one child process should die.

Parameters

pod	the pipe-of-death to write to.
graceful	restart-type

ap_mpm_rewrite_args()

void ap_mpm_rewrite_args

(

process_rec *

)

ap_mpm_safe_kill()

apr_status_t ap_mpm_safe_kill	(	pid_t	pid,
		int	sig
	)

Safely signal an MPM child process, if the process is in the current process group. Otherwise fail.

Parameters

pid	the process id of a child process to signal
sig	the signal number to send

Returns

APR_SUCCESS if signal is sent, otherwise an error as per kill(3); APR_EINVAL is returned if passed either an invalid (< 1) pid, or if the pid is not in the current process group

ap_mpm_set_coredumpdir()

const char* ap_mpm_set_coredumpdir	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_mpm_set_graceful_shutdown()

const char* ap_mpm_set_graceful_shutdown	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_mpm_set_max_mem_free()

const char* ap_mpm_set_max_mem_free	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_mpm_set_max_requests()

const char* ap_mpm_set_max_requests	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_mpm_set_pidfile()

const char* ap_mpm_set_pidfile	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_mpm_set_thread_stacksize()

const char* ap_mpm_set_thread_stacksize	(	cmd_parms *	cmd,
		void *	dummy,
		const char *	arg
	)

ap_process_child_status()

int ap_process_child_status	(	apr_proc_t *	pid,
		apr_exit_why_e	why,
		int	status
	)

Log why a child died to the error log, if the child died without the parent signalling it.

Parameters

pid	The child that has died
why	The return code of the child process
status	The status returned from ap_wait_or_timeout

Returns

0 on success, APEXIT_CHILDFATAL if MPM should terminate

ap_reclaim_child_processes()

void ap_reclaim_child_processes	(	int	terminate,
		ap_reclaim_callback_fn_t *	mpm_callback
	)

Make sure all child processes that have been spawned by the parent process have died. This includes process registered as "other_children".

Parameters

terminate	Either 1 or 0. If 1, send the child processes SIGTERM each time through the loop. If 0, give the process time to die on its own before signalling it.
mpm_callback	Callback invoked for each dead child process

Note

The MPM child processes which are reclaimed are those listed in the scoreboard as well as those currently registered via ap_register_extra_mpm_process().

ap_register_extra_mpm_process()

void ap_register_extra_mpm_process	(	pid_t	pid,
		ap_generation_t	gen
	)

Tell ap_reclaim_child_processes() and ap_relieve_child_processes() about an MPM child process which has no entry in the scoreboard.

Parameters

pid	The process id of an MPM child process which should be reclaimed when ap_reclaim_child_processes() is called.
gen	The generation of this MPM child process.

Note

If an extra MPM child process terminates prior to calling ap_reclaim_child_processes(), remove it from the list of such processes by calling ap_unregister_extra_mpm_process().

ap_relieve_child_processes()

void ap_relieve_child_processes

(

ap_reclaim_callback_fn_t *

mpm_callback

)

Catch any child processes that have been spawned by the parent process which have exited. This includes processes registered as "other_children".

Parameters

mpm_callback

Callback invoked for each dead child process

Note

The MPM child processes which are relieved are those listed in the scoreboard as well as those currently registered via ap_register_extra_mpm_process().

ap_signal_server()

int ap_signal_server	(	int *	,
		apr_pool_t *
	)

ap_sys_privileges_handlers()

int ap_sys_privileges_handlers

(

int

inc

)

ap_uname2id()

uid_t ap_uname2id

(

const char *

name

)

Convert a username to a numeric ID

Parameters

name	The name to convert

Returns

The user id corresponding to a name

ap_unregister_extra_mpm_process()

int ap_unregister_extra_mpm_process	(	pid_t	pid,
		ap_generation_t *	old_gen
	)

Unregister an MPM child process which was previously registered by a call to ap_register_extra_mpm_process().

Parameters

pid	The process id of an MPM child process which no longer needs to be reclaimed.
old_gen	Set to the server generation of the process, if found.

Returns

1 if the process was found and removed, 0 otherwise

ap_wait_or_timeout()

void ap_wait_or_timeout	(	apr_exit_why_e *	status,
		int *	exitcode,
		apr_proc_t *	ret,
		apr_pool_t *	p,
		server_rec *	s
	)

Run the monitor hook (once every ten calls), determine if any child process has died and, if none died, sleep one second.

Parameters

status	The return code if a process has died
exitcode	The returned exit status of the child, if a child process dies, or the signal that caused the child to die.
ret	The process id of the process that died
p	The pool to allocate out of
s	The server_rec to pass

child_stopped()

void child_stopped	(	apr_pool_t *	pchild,
		int	graceful
	)

Notification that the child has stopped processing requests completely. Any running threads should be shut down now. Ideally, when this hook completes, no more threads are running in the child process. Note that de-allocation of global resources should be run via memory pool destroy callback after this.

Parameters

pchild	The child pool
graceful	!= 0 iff this is a graceful shutdown.

child_stopping()

void child_stopping	(	apr_pool_t *	pchild,
		int	graceful
	)

Notification that the child is stopping. No new requests or other tasks to be started. If graceful, already started requests/tasks should be processed normally.

Parameters

pchild	The child pool
graceful	!= 0 iff this is a graceful shutdown.

drop_privileges()

int drop_privileges	(	apr_pool_t *	pchild,
		server_rec *	s
	)

mpm_common_pre_config()

void mpm_common_pre_config

(

apr_pool_t *

pconf

)

mpm_register_poll_callback_timeout()

apr_status_t mpm_register_poll_callback_timeout	(	apr_pool_t *	p,
		const apr_array_header_t *	pds,
		ap_mpm_callback_fn_t *	cbfn,
		ap_mpm_callback_fn_t *	tofn,
		void *	baton,
		apr_time_t	timeout
	)

Variable Documentation

ap_coredump_dir

AP_DECLARE_DATA char ap_coredump_dir[MAX_STRING_LEN]

extern

ap_coredumpdir_configured

AP_DECLARE_DATA int ap_coredumpdir_configured

extern

ap_graceful_shutdown_timeout

AP_DECLARE_DATA int ap_graceful_shutdown_timeout

extern

Set the timeout period for a graceful shutdown.

ap_max_mem_free

AP_DECLARE_DATA apr_uint32_t ap_max_mem_free

extern

ap_max_requests_per_child

AP_DECLARE_DATA int ap_max_requests_per_child

extern

The maximum number of requests each child thread or process handles before dying off

ap_pid_fname

AP_DECLARE_DATA const char* ap_pid_fname

extern

The filename used to store the process id.

ap_thread_stacksize

AP_DECLARE_DATA apr_size_t ap_thread_stacksize

extern