Collaboration diagram for Threads and Process Functions:

Classes
struct	apr_proc_t
Modules
	Other Child Flags
Defines
#define	APR_PROC_CHECK_EXIT(x) (x & APR_PROC_EXIT)
#define	APR_PROC_CHECK_SIGNALED(x) (x & APR_PROC_SIGNAL)
#define	APR_PROC_CHECK_CORE_DUMP(x) (x & APR_PROC_SIGNAL_CORE)
#define	APR_NO_PIPE 0
#define	APR_FULL_BLOCK 1
#define	APR_FULL_NONBLOCK 2
#define	APR_PARENT_BLOCK 3
#define	APR_CHILD_BLOCK 4
#define	APR_NO_FILE 8
#define	APR_NO_FILE 8
#define	APR_READ_BLOCK 3
#define	APR_WRITE_BLOCK 4
#define	APR_LIMIT_CPU 0
#define	APR_LIMIT_MEM 1
#define	APR_LIMIT_NPROC 2
#define	APR_LIMIT_NOFILE 3
#define	APR_PROC_DETACH_FOREGROUND 0
#define	APR_PROC_DETACH_DAEMONIZE 1
Typedefs
typedef struct apr_proc_t	apr_proc_t
typedef void(	apr_child_errfn_t )(apr_pool_t proc, apr_status_t err, const char description)
typedef struct apr_thread_t	apr_thread_t
typedef struct apr_threadattr_t	apr_threadattr_t
typedef struct apr_procattr_t	apr_procattr_t
typedef struct apr_thread_once_t	apr_thread_once_t
typedef struct apr_threadkey_t	apr_threadkey_t
typedef struct apr_other_child_rec_t	apr_other_child_rec_t
typedef void (APR_THREAD_FUNC	apr_thread_start_t )(apr_thread_t , void )
Enumerations
enum	apr_cmdtype_e { APR_SHELLCMD, APR_PROGRAM, APR_PROGRAM_ENV, APR_PROGRAM_PATH, APR_SHELLCMD_ENV }
enum	apr_wait_how_e { APR_WAIT, APR_NOWAIT }
enum	apr_exit_why_e { APR_PROC_EXIT = 1, APR_PROC_SIGNAL = 2, APR_PROC_SIGNAL_CORE = 4 }
enum	apr_kill_conditions_e { APR_KILL_NEVER, APR_KILL_ALWAYS, APR_KILL_AFTER_TIMEOUT, APR_JUST_WAIT, APR_KILL_ONLY_ONCE }
Functions
	APR_DECLARE (apr_status_t) apr_procattr_create(apr_procattr_t **new_attr
	APR_DECLARE (void) apr_proc_other_child_register(apr_proc_t *proc
Variables
apr_pool_t *	cont
apr_int32_t	in
apr_int32_t apr_int32_t	out
apr_int32_t apr_int32_t apr_int32_t	err
apr_file_t *	child_in
apr_file_t apr_file_t *	parent_in
apr_file_t *	child_out
apr_file_t apr_file_t *	parent_out
apr_file_t *	child_err
apr_file_t apr_file_t *	parent_err
const char *	dir
apr_cmdtype_e	cmd
apr_int32_t	detach
apr_child_errfn_t *	errfn
apr_int32_t	chk
apr_int32_t	addrspace
const char *	username
const char const char *	password
const char *	groupname
const char *	progname
const char const char const	args
const char const char const const char const *	env
const char const char const const char const apr_procattr_t *	attr
const char const char const const char const apr_procattr_t apr_pool_t *	pool
int *	exitcode
int apr_exit_why_e *	exitwhy
int apr_exit_why_e apr_wait_how_e	waithow
int apr_exit_why_e apr_wait_how_e apr_pool_t *	p
void(*	maintenance )(int reason, void *, int status)
void(*) void	data )
void(*) void apr_file_t	write_fd )
int	reason
int int	status
int	sig
apr_proc_t *	proc
apr_proc_t apr_kill_conditions_e	how

Define Documentation

#define APR_CHILD_BLOCK 4

See also:: apr_procattr_io_set

Definition at line 87 of file apr_thread_proc.h.

#define APR_FULL_BLOCK 1

See also:: apr_procattr_io_set and apr_file_pipe_create_ex

Definition at line 81 of file apr_thread_proc.h.

#define APR_FULL_NONBLOCK 2

See also:: apr_procattr_io_set and apr_file_pipe_create_ex

Definition at line 83 of file apr_thread_proc.h.

#define APR_LIMIT_CPU 0

See also:: apr_procattr_limit_set

Definition at line 102 of file apr_thread_proc.h.

#define APR_LIMIT_MEM 1

See also:: apr_procattr_limit_set

Definition at line 104 of file apr_thread_proc.h.

#define APR_LIMIT_NOFILE 3

See also:: apr_procattr_limit_set

Definition at line 108 of file apr_thread_proc.h.

#define APR_LIMIT_NPROC 2

See also:: apr_procattr_limit_set

Definition at line 106 of file apr_thread_proc.h.

#define APR_NO_FILE 8

See also:: apr_procattr_io_set; apr_procattr_io_set

Note:: Win32 only effective with version 1.2.12, portably introduced in 1.3.0

Definition at line 99 of file apr_thread_proc.h.

#define APR_NO_FILE 8

See also:: apr_procattr_io_set; apr_procattr_io_set

Note:: Win32 only effective with version 1.2.12, portably introduced in 1.3.0

Definition at line 99 of file apr_thread_proc.h.

#define APR_NO_PIPE 0

See also:: apr_procattr_io_set

Definition at line 79 of file apr_thread_proc.h.

#define APR_PARENT_BLOCK 3

See also:: apr_procattr_io_set

Definition at line 85 of file apr_thread_proc.h.

#define APR_PROC_CHECK_CORE_DUMP ( x ) (x & APR_PROC_SIGNAL_CORE)

did we get core

Definition at line 76 of file apr_thread_proc.h.

#define APR_PROC_CHECK_EXIT ( x ) (x & APR_PROC_EXIT)

did we exit the process

Definition at line 72 of file apr_thread_proc.h.

#define APR_PROC_CHECK_SIGNALED ( x ) (x & APR_PROC_SIGNAL)

did we get a signal

Definition at line 74 of file apr_thread_proc.h.

#define APR_PROC_DETACH_DAEMONIZE 1

Detach

Definition at line 678 of file apr_thread_proc.h.

#define APR_PROC_DETACH_FOREGROUND 0

Do not detach

Definition at line 677 of file apr_thread_proc.h.

#define APR_READ_BLOCK 3

See also:: apr_file_pipe_create_ex

Definition at line 92 of file apr_thread_proc.h.

#define APR_WRITE_BLOCK 4

See also:: apr_file_pipe_create_ex

Definition at line 94 of file apr_thread_proc.h.

Typedef Documentation

typedef void( apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err, const char *description)

The prototype for APR child errfn functions. (See the description of apr_procattr_child_errfn_set() for more information.) It is passed the following parameters:

Parameters:

pool	Pool associated with the apr_proc_t. If your child error function needs user data, associate it with this pool.
err	APR error code describing the error
description	Text description of type of processing which failed

Definition at line 173 of file apr_thread_proc.h.

typedef struct apr_other_child_rec_t apr_other_child_rec_t

Opaque record of child process.

Definition at line 192 of file apr_thread_proc.h.

typedef struct apr_proc_t apr_proc_t

The APR process type

typedef struct apr_procattr_t apr_procattr_t

Opaque Process attributes structure.

Definition at line 183 of file apr_thread_proc.h.

typedef struct apr_thread_once_t apr_thread_once_t

Opaque control variable for one-time atomic variables.

Definition at line 186 of file apr_thread_proc.h.

typedef void*(APR_THREAD_FUNC * apr_thread_start_t)(apr_thread_t *, void *)

The prototype for any APR thread worker functions.

Definition at line 197 of file apr_thread_proc.h.

typedef struct apr_thread_t apr_thread_t

Opaque Thread structure.

Definition at line 177 of file apr_thread_proc.h.

typedef struct apr_threadattr_t apr_threadattr_t

Opaque Thread attributes structure.

Definition at line 180 of file apr_thread_proc.h.

typedef struct apr_threadkey_t apr_threadkey_t

Opaque thread private address space.

Definition at line 189 of file apr_thread_proc.h.

Enumeration Type Documentation

enum apr_cmdtype_e

Enumerator:

APR_SHELLCMD	use the shell to invoke the program
APR_PROGRAM	invoke the program directly, no copied env
APR_PROGRAM_ENV	invoke the program, replicating our environment
APR_PROGRAM_PATH	find program on PATH, use our environment
APR_SHELLCMD_ENV	use the shell to invoke the program, replicating our environment

Definition at line 45 of file apr_thread_proc.h.

enum apr_exit_why_e

Enumerator:

APR_PROC_EXIT	process exited normally
APR_PROC_SIGNAL	process exited due to a signal
APR_PROC_SIGNAL_CORE	process exited and dumped a core file

Definition at line 65 of file apr_thread_proc.h.

enum apr_kill_conditions_e

Enumerator:

APR_KILL_NEVER	process is never sent any signals
APR_KILL_ALWAYS	process is sent SIGKILL on apr_pool_t cleanup
APR_KILL_AFTER_TIMEOUT	SIGTERM, wait 3 seconds, SIGKILL
APR_JUST_WAIT	wait forever for the process to complete
APR_KILL_ONLY_ONCE	send SIGTERM and then wait

Definition at line 199 of file apr_thread_proc.h.

enum apr_wait_how_e

Enumerator:

APR_WAIT	wait for the specified process to finish
APR_NOWAIT	do not wait -- just see if it has finished

Definition at line 55 of file apr_thread_proc.h.

Function Documentation

APR_DECLARE ( apr_status_t )

Create and initialize a new procattr variable

Parameters:

new_attr	The newly created procattr.
cont	The pool to use

Determine if any of stdin, stdout, or stderr should be linked to pipes when starting a child process.

Parameters:

attr	The procattr we care about.
in	Should stdin be a pipe back to the parent?
out	Should stdout be a pipe back to the parent?
err	Should stderr be a pipe back to the parent?

Note:: If APR_NO_PIPE, there will be no special channel, the child inherits the parent's corresponding stdio stream. If APR_NO_FILE is specified, that corresponding stream is closed in the child (and will be INVALID_HANDLE_VALUE when inspected on Win32). This can have ugly side effects, as the next file opened in the child on Unix will fall into the stdio stream fd slot!

Set the child_in and/or parent_in values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_in	apr_file_t value to use as child_in. Must be a valid file.
parent_in	apr_file_t value to use as parent_in. Must be a valid file.

Remarks:: This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file. You can save some extra function calls by not creating your own pipe since this creates one in the process space for you.

Bug:: Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:: apr_procattr_io_set instead for simple pipes.

Set the child_out and parent_out values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_out	apr_file_t value to use as child_out. Must be a valid file.
parent_out	apr_file_t value to use as parent_out. Must be a valid file.

Remarks:: This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.

Bug:: Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:: apr_procattr_io_set instead for simple pipes.

Set the child_err and parent_err values to existing apr_file_t values.

Parameters:

attr	The procattr we care about.
child_err	apr_file_t value to use as child_err. Must be a valid file.
parent_err	apr_file_t value to use as parent_err. Must be a valid file.

Remarks:: This is NOT a required initializer function. This is useful if you have already opened a pipe (or multiple files) that you wish to use, perhaps persistently across multiple process invocations - such as a log file.

Bug:: Note that calling this function with two NULL files on some platforms creates an APR_FULL_BLOCK pipe, but this behavior is neither portable nor is it supported.

See also:: apr_procattr_io_set instead for simple pipes.

Set which directory the child process should start executing in.

Parameters:

attr	The procattr we care about.
dir	Which dir to start in. By default, this is the same dir as the parent currently resides in, when the createprocess call is made.

Set what type of command the child process will call.

Parameters:

attr The procattr we care about.

cmd

The type of command. One of:

            APR_SHELLCMD     --  Anything that the shell can handle
            APR_PROGRAM      --  Executable program   (default) 
            APR_PROGRAM_ENV  --  Executable program, copy environment
            APR_PROGRAM_PATH --  Executable program on PATH, copy env

Determine if the child should start in detached state.

Parameters:

attr	The procattr we care about.
detach	Should the child start in detached state? Default is no.

Specify an error function to be called in the child process if APR encounters an error in the child prior to running the specified program.

Parameters:

attr	The procattr describing the child process to be created.
errfn	The function to call in the child process.

Remarks:: At the present time, it will only be called from apr_proc_create() on platforms where fork() is used. It will never be called on other platforms, on those platforms apr_proc_create() will return the error in the parent process rather than invoke the callback in the now-forked child process.

Specify that apr_proc_create() should do whatever it can to report failures to the caller of apr_proc_create(), rather than find out in the child.

Parameters:

attr	The procattr describing the child process to be created.
chk	Flag to indicate whether or not extra work should be done to try to report failures to the caller.

Remarks:: This flag only affects apr_proc_create() on platforms where fork() is used. This leads to extra overhead in the calling process, but that may help the application handle such errors more gracefully.

Determine if the child should start in its own address space or using the current one from its parent

Parameters:

attr	The procattr we care about.
addrspace	Should the child start in its own address space? Default is no on NetWare and yes on other platforms.

Set the username used for running process

Parameters:

attr	The procattr we care about.
username	The username used
password	User password if needed. Password is needed on WIN32 or any other platform having APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.

Set the group used for running process

Parameters:

attr	The procattr we care about.
groupname	The group name used

Create a new process and execute a new program within that process.

Parameters:

new_proc	The resulting process handle.
progname	The program to run
args	the arguments to pass to the new program. The first one should be the program name.
env	The new environment table for the new process. This should be a list of NULL-terminated strings. This argument is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and APR_SHELLCMD_ENV types of commands.
attr	the procattr we should use to determine how to create the new process
pool	The pool to use.

Note:: This function returns without waiting for the new process to terminate; use apr_proc_wait for that.

Wait for a child process to die

Parameters:

proc	The process handle that corresponds to the desired child process
exitcode	The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL.
exitwhy	Why the child died, the bitwise or of: APR_PROC_EXIT -- process terminated normally APR_PROC_SIGNAL -- process was killed by a signal APR_PROC_SIGNAL_CORE -- process was killed by a signal, and generated a core dump.
waithow	How should we wait. One of: APR_WAIT -- block until the child process dies. APR_NOWAIT -- return immediately regardless of if the child is dead or not.

Remarks:

The childs status is in the return code to this process. It is one of:

            APR_CHILD_DONE     -- child is no longer running.
            APR_CHILD_NOTDONE  -- child is still running.

Wait for any current child process to die and return information about that child.

Parameters:

proc	Pointer to NULL on entry, will be filled out with child's information
exitcode	The returned exit status of the child, if a child process dies, or the signal that caused the child to die. On platforms that don't support obtaining this information, the status parameter will be returned as APR_ENOTIMPL.
exitwhy	Why the child died, the bitwise or of: APR_PROC_EXIT -- process terminated normally APR_PROC_SIGNAL -- process was killed by a signal APR_PROC_SIGNAL_CORE -- process was killed by a signal, and generated a core dump.
waithow	How should we wait. One of: APR_WAIT -- block until the child process dies. APR_NOWAIT -- return immediately regardless of if the child is dead or not.
p	Pool to allocate child information out of.

Bug:: Passing proc as a *proc rather than **proc was an odd choice for some platforms... this should be revisited in 1.0

Detach the process from the controlling terminal.

Parameters:

daemonize set to non-zero if the process should daemonize and become a background process, else it will stay in the foreground.

Notify the maintenance callback of a registered other child process that application has detected an event, such as death.

Parameters:

proc	The process to check
reason	The reason code to pass to the maintenance function
status	The status to pass to the maintenance function

Remarks:

An example of code using this behavior;

 rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
 if (APR_STATUS_IS_CHILD_DONE(rv)) {
 #if APR_HAS_OTHER_CHILD
     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
             == APR_SUCCESS) {
         ;  (already handled)
     }
     else
 #endif
         [... handling non-otherchild processes death ...]

Terminate a process.

Parameters:

proc	The process to terminate.
sig	How to kill the process.

APR_DECLARE ( void )

Register an other_child -- a child associated to its registered maintence callback. This callback is invoked when the process dies, is disconnected or disappears.

Parameters:

proc	The child process to register.
maintenance	maintenance is a function that is invoked with a reason and the data pointer passed here.
data	Opaque context data passed to the maintenance function.
write_fd	An fd that is probed for writing. If it is ever unwritable then the maintenance is invoked with reason OC_REASON_UNWRITABLE.
p	The pool to use for allocating memory.

Bug:

write_fd duplicates the proc->out stream, it's really redundant and should be replaced in the APR 1.0 API with a bitflag of which proc->in/out/err handles should be health checked.

no platform currently tests the pipes health.

Stop watching the specified other child.

Parameters:

data	The data to pass to the maintenance function. This is used to find the process to unregister.

Warning:: Since this can be called by a maintenance function while we're scanning the other_children list, all scanners should protect themself by loading ocr->next before calling any maintenance function.

Test one specific other child processes and invoke the maintenance callback with the appropriate reason code, if still running, or the appropriate reason code if the process is no longer healthy.

Parameters:

ocr	The registered other child
reason	The reason code (e.g. APR_OC_REASON_RESTART) if still running

Test all registered other child processes and invoke the maintenance callback with the appropriate reason code, if still running, or the appropriate reason code if the process is no longer healthy.

Parameters:

reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes

Register a process to be killed when a pool dies.

Parameters:

a The pool to use to define the processes lifetime

proc The process to register

how

How to kill the process, one of:

         APR_KILL_NEVER         -- process is never sent any signals
         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
         APR_JUST_WAIT          -- wait forever for the process to complete
         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait