Threads and Process Functions

Overview

Other Child Flags

// 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 *
    );

// enums

enum apr_cmdtype_e;
enum apr_exit_why_e;
enum apr_kill_conditions_e;
enum apr_wait_how_e;

// structs

struct apr_proc_t;

// global functions

apr_status_t
apr_threadattr_create(
    apr_threadattr_t** new_attr,
    apr_pool_t* cont
);

apr_status_t
apr_threadattr_detach_set(
    apr_threadattr_t* attr,
    apr_int32_t on
);

apr_status_t
apr_threadattr_detach_get(apr_threadattr_t* attr);

apr_status_t
apr_threadattr_stacksize_set(
    apr_threadattr_t* attr,
    apr_size_t stacksize
);

apr_status_t
apr_threadattr_guardsize_set(
    apr_threadattr_t* attr,
    apr_size_t guardsize
);

apr_status_t
apr_thread_create(
    apr_thread_t** new_thread,
    apr_threadattr_t* attr,
    apr_thread_start_t func,
    void* data,
    apr_pool_t* cont
);

apr_status_t
apr_thread_exit(
    apr_thread_t* thd,
    apr_status_t retval
);

apr_status_t
apr_thread_join(
    apr_status_t* retval,
    apr_thread_t* thd
);

void
apr_thread_yield(void);

apr_status_t
apr_thread_once_init(
    apr_thread_once_t** control,
    apr_pool_t* p
);

apr_status_t
apr_thread_once(
    apr_thread_once_t* control,
    void(*)(void) func
);

apr_status_t
apr_thread_detach(apr_thread_t* thd);

apr_status_t
apr_thread_data_get(
    void** data,
    const char* key,
    apr_thread_t* thread
);

apr_status_t
apr_thread_data_set(
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup,
    apr_thread_t* thread
);

apr_status_t
apr_threadkey_private_create(
    apr_threadkey_t** key,
    void(*)(void*) dest,
    apr_pool_t* cont
);

apr_status_t
apr_threadkey_private_get(
    void** new_mem,
    apr_threadkey_t* key
);

apr_status_t
apr_threadkey_private_set(
    void* priv,
    apr_threadkey_t* key
);

apr_status_t
apr_threadkey_private_delete(apr_threadkey_t* key);

apr_status_t
apr_threadkey_data_get(
    void** data,
    const char* key,
    apr_threadkey_t* threadkey
);

apr_status_t
apr_threadkey_data_set(
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup,
    apr_threadkey_t* threadkey
);

apr_status_t
apr_procattr_create(
    apr_procattr_t** new_attr,
    apr_pool_t* cont
);

apr_status_t
apr_procattr_io_set(
    apr_procattr_t* attr,
    apr_int32_t in,
    apr_int32_t out,
    apr_int32_t err
);

apr_status_t
apr_procattr_child_in_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_in,
    apr_file_t* parent_in
);

apr_status_t
apr_procattr_child_out_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_out,
    apr_file_t* parent_out
);

apr_status_t
apr_procattr_child_err_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_err,
    apr_file_t* parent_err
);

apr_status_t
apr_procattr_dir_set(
    apr_procattr_t* attr,
    const char* dir
);

apr_status_t
apr_procattr_cmdtype_set(
    apr_procattr_t* attr,
    apr_cmdtype_e cmd
);

apr_status_t
apr_procattr_detach_set(
    apr_procattr_t* attr,
    apr_int32_t detach
);

apr_status_t
apr_procattr_limit_set(
    apr_procattr_t* attr,
    apr_int32_t what,
    struct rlimit* limit
);

apr_status_t
apr_procattr_child_errfn_set(
    apr_procattr_t* attr,
    apr_child_errfn_t* errfn
);

apr_status_t
apr_procattr_error_check_set(
    apr_procattr_t* attr,
    apr_int32_t chk
);

apr_status_t
apr_procattr_addrspace_set(
    apr_procattr_t* attr,
    apr_int32_t addrspace
);

apr_status_t
apr_procattr_user_set(
    apr_procattr_t* attr,
    const char* username,
    const char* password
);

apr_status_t
apr_procattr_group_set(
    apr_procattr_t* attr,
    const char* groupname
);

apr_status_t
apr_proc_fork(
    apr_proc_t* proc,
    apr_pool_t* cont
);

apr_status_t
apr_proc_create(
    apr_proc_t* new_proc,
    const char* progname,
    const char*const* args,
    const char*const* env,
    apr_procattr_t* attr,
    apr_pool_t* pool
);

apr_status_t
apr_proc_wait(
    apr_proc_t* proc,
    int* exitcode,
    apr_exit_why_e* exitwhy,
    apr_wait_how_e waithow
);

apr_status_t
apr_proc_wait_all_procs(
    apr_proc_t* proc,
    int* exitcode,
    apr_exit_why_e* exitwhy,
    apr_wait_how_e waithow,
    apr_pool_t* p
);

apr_status_t
apr_proc_detach(int daemonize);

void
apr_proc_other_child_register(
    apr_proc_t* proc,
    void(*)(int reason, void*, int status) maintenance,
    void* data,
    apr_file_t* write_fd,
    apr_pool_t* p
);

void
apr_proc_other_child_unregister(void* data);

apr_status_t
apr_proc_other_child_alert(
    apr_proc_t* proc,
    int reason,
    int status
);

void
apr_proc_other_child_refresh(
    apr_other_child_rec_t* ocr,
    int reason
);

void
apr_proc_other_child_refresh_all(int reason);

apr_status_t
apr_proc_kill(
    apr_proc_t* proc,
    int sig
);

void
apr_pool_note_subprocess(
    apr_pool_t* a,
    apr_proc_t* proc,
    apr_kill_conditions_e how
);

apr_status_t
apr_setup_signal_thread(void);

apr_status_t
apr_signal_thread(int(*)(int signum) signal_handler);

apr_pool_t*
apr_thread_pool_get(const apr_thread_t* thethread);

// macros

#define APR_CHILD_BLOCK
#define APR_FULL_BLOCK
#define APR_FULL_NONBLOCK
#define APR_LIMIT_CPU
#define APR_LIMIT_MEM
#define APR_LIMIT_NOFILE
#define APR_LIMIT_NPROC
#define APR_NO_FILE
#define APR_NO_PIPE
#define APR_PARENT_BLOCK
#define APR_PROC_CHECK_CORE_DUMP(x)
#define APR_PROC_CHECK_EXIT(x)
#define APR_PROC_CHECK_SIGNALED(x)
#define APR_PROC_DETACH_DAEMONIZE
#define APR_PROC_DETACH_FOREGROUND
#define APR_READ_BLOCK
#define APR_WRITE_BLOCK

Detailed Documentation

Typedefs

typedef struct apr_proc_t apr_proc_t

The APR process type

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

typedef struct apr_thread_t apr_thread_t

Opaque Thread structure.

typedef struct apr_threadattr_t apr_threadattr_t

Opaque Thread attributes structure.

typedef struct apr_procattr_t apr_procattr_t

Opaque Process attributes structure.

typedef struct apr_thread_once_t apr_thread_once_t

Opaque control variable for one-time atomic variables.

typedef struct apr_threadkey_t apr_threadkey_t

Opaque thread private address space.

typedef struct apr_other_child_rec_t apr_other_child_rec_t

Opaque record of child process.

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

The prototype for any APR thread worker functions.

Global Functions

apr_status_t
apr_threadattr_create(
    apr_threadattr_t** new_attr,
    apr_pool_t* cont
)

Create and initialize a new threadattr variable

Parameters:

new_attr	The newly created threadattr.
cont	The pool to use

apr_status_t
apr_threadattr_detach_set(
    apr_threadattr_t* attr,
    apr_int32_t on
)

Set if newly created threads should be created in detached state.

Parameters:

attr	The threadattr to affect
on	Non-zero if detached threads should be created.

apr_status_t
apr_threadattr_detach_get(apr_threadattr_t* attr)

Get the detach state for this threadattr.

Parameters:

attr	The threadattr to reference

Returns:

APR_DETACH if threads are to be detached, or APR_NOTDETACH if threads are to be joinable.

apr_status_t
apr_threadattr_stacksize_set(
    apr_threadattr_t* attr,
    apr_size_t stacksize
)

Set the stack size of newly created threads.

Parameters:

attr	The threadattr to affect
stacksize	The stack size in bytes

apr_status_t
apr_threadattr_guardsize_set(
    apr_threadattr_t* attr,
    apr_size_t guardsize
)

Set the stack guard area size of newly created threads.

Note

Thread library implementations commonly use a “guard area” after each thread’s stack which is not readable or writable such that stack overflows cause a segfault; this consumes e.g. 4K of memory and increases memory management overhead. Setting the guard area size to zero hence trades off reliable behaviour on stack overflow for performance.

Parameters:

attr	The threadattr to affect
guardsize	The stack guard area size in bytes

apr_status_t
apr_thread_create(
    apr_thread_t** new_thread,
    apr_threadattr_t* attr,
    apr_thread_start_t func,
    void* data,
    apr_pool_t* cont
)

Create a new thread of execution

Parameters:

new_thread	The newly created thread handle.
attr	The threadattr to use to determine how to create the thread
func	The function to start the new thread in
data	Any data to be passed to the starting function
cont	The pool to use

apr_status_t
apr_thread_exit(
    apr_thread_t* thd,
    apr_status_t retval
)

stop the current thread

Parameters:

thd	The thread to stop
retval	The return value to pass back to any thread that cares

apr_status_t
apr_thread_join(
    apr_status_t* retval,
    apr_thread_t* thd
)

block until the desired thread stops executing.

Parameters:

retval	The return value from the dead thread.
thd	The thread to join

void
apr_thread_yield(void)

force the current thread to yield the processor

apr_status_t
apr_thread_once_init(
    apr_thread_once_t** control,
    apr_pool_t* p
)

Initialize the control variable for apr_thread_once. If this isn’t called, apr_initialize won’t work.

Parameters:

control	The control variable to initialize
p	The pool to allocate data from.

apr_status_t
apr_thread_once(
    apr_thread_once_t* control,
    void(*)(void) func
)

Run the specified function one time, regardless of how many threads call it.

Parameters:

control	The control variable. The same variable should be passed in each time the function is tried to be called. This is how the underlying functions determine if the function has ever been called before.
func	The function to call.

apr_status_t
apr_thread_detach(apr_thread_t* thd)

detach a thread

Parameters:

thd	The thread to detach

apr_status_t
apr_thread_data_get(
    void** data,
    const char* key,
    apr_thread_t* thread
)

Return user data associated with the current thread.

Parameters:

data	The user data associated with the thread.
key	The key to associate with the data
thread	The currently open thread.

apr_status_t
apr_thread_data_set(
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup,
    apr_thread_t* thread
)

Set user data associated with the current thread.

Parameters:

data	The user data to associate with the thread.
key	The key to use for associating the data with the thread
cleanup	The cleanup routine to use when the thread is destroyed.
thread	The currently open thread.

apr_status_t
apr_threadkey_private_create(
    apr_threadkey_t** key,
    void(*)(void*) dest,
    apr_pool_t* cont
)

Create and initialize a new thread private address space

Parameters:

key	The thread private handle.
dest	The destructor to use when freeing the private memory.
cont	The pool to use

apr_status_t
apr_threadkey_private_get(
    void** new_mem,
    apr_threadkey_t* key
)

Get a pointer to the thread private memory

Parameters:

new_mem	The data stored in private memory
key	The handle for the desired thread private memory

apr_status_t
apr_threadkey_private_set(
    void* priv,
    apr_threadkey_t* key
)

Set the data to be stored in thread private memory

Parameters:

priv	The data to be stored in private memory
key	The handle for the desired thread private memory

apr_status_t
apr_threadkey_private_delete(apr_threadkey_t* key)

Free the thread private memory

Parameters:

key	The handle for the desired thread private memory

apr_status_t
apr_threadkey_data_get(
    void** data,
    const char* key,
    apr_threadkey_t* threadkey
)

Return the pool associated with the current threadkey.

Parameters:

data	The user data associated with the threadkey.
key	The key associated with the data
threadkey	The currently open threadkey.

apr_status_t
apr_threadkey_data_set(
    void* data,
    const char* key,
    apr_status_t(*)(void*) cleanup,
    apr_threadkey_t* threadkey
)

Return the pool associated with the current threadkey.

Parameters:

data	The data to set.
key	The key to associate with the data.
cleanup	The cleanup routine to use when the file is destroyed.
threadkey	The currently open threadkey.

apr_status_t
apr_procattr_create(
    apr_procattr_t** new_attr,
    apr_pool_t* cont
)

Create and initialize a new procattr variable

Parameters:

new_attr	The newly created procattr.
cont	The pool to use

apr_status_t
apr_procattr_io_set(
    apr_procattr_t* attr,
    apr_int32_t in,
    apr_int32_t out,
    apr_int32_t err
)

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

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!

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?

apr_status_t
apr_procattr_child_in_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_in,
    apr_file_t* parent_in
)

Set the child_in and/or parent_in values to existing apr_file_t values. 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.

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.

See also:

apr_procattr_io_set instead for simple pipes.

apr_status_t
apr_procattr_child_out_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_out,
    apr_file_t* parent_out
)

Set the child_out and parent_out values to existing apr_file_t values. 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.

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.

See also:

apr_procattr_io_set instead for simple pipes.

apr_status_t
apr_procattr_child_err_set(
    struct apr_procattr_t* attr,
    apr_file_t* child_err,
    apr_file_t* parent_err
)

Set the child_err and parent_err values to existing apr_file_t values. 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.

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.

See also:

apr_procattr_io_set instead for simple pipes.

apr_status_t
apr_procattr_dir_set(
    apr_procattr_t* attr,
    const char* dir
)

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.

apr_status_t
apr_procattr_cmdtype_set(
    apr_procattr_t* attr,
    apr_cmdtype_e cmd
)

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

apr_status_t
apr_procattr_detach_set(
    apr_procattr_t* attr,
    apr_int32_t detach
)

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.

apr_status_t
apr_procattr_limit_set(
    apr_procattr_t* attr,
    apr_int32_t what,
    struct rlimit* limit
)

Set the Resource Utilization limits when starting a new process.

Parameters:

attr	The procattr we care about.
what	Which limit to set, one of: APR_LIMIT_CPU APR_LIMIT_MEM APR_LIMIT_NPROC APR_LIMIT_NOFILE
limit	Value to set the limit to.

apr_status_t
apr_procattr_child_errfn_set(
    apr_procattr_t* attr,
    apr_child_errfn_t* errfn
)

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. 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.

Parameters:

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

apr_status_t
apr_procattr_error_check_set(
    apr_procattr_t* attr,
    apr_int32_t chk
)

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. 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.

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.

apr_status_t
apr_procattr_addrspace_set(
    apr_procattr_t* attr,
    apr_int32_t addrspace
)

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.

apr_status_t
apr_procattr_user_set(
    apr_procattr_t* attr,
    const char* username,
    const char* password
)

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.

apr_status_t
apr_procattr_group_set(
    apr_procattr_t* attr,
    const char* groupname
)

Set the group used for running process

Parameters:

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

apr_status_t
apr_proc_fork(
    apr_proc_t* proc,
    apr_pool_t* cont
)

This is currently the only non-portable call in APR. This executes a standard unix fork. returns APR_INCHILD for the child, and APR_INPARENT for the parent or an error.

Parameters:

proc	The resulting process handle.
cont	The pool to use.

apr_status_t
apr_proc_create(
    apr_proc_t* new_proc,
    const char* progname,
    const char*const* args,
    const char*const* env,
    apr_procattr_t* attr,
    apr_pool_t* pool
)

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

Note

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

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.

apr_status_t
apr_proc_wait(
    apr_proc_t* proc,
    int* exitcode,
    apr_exit_why_e* exitwhy,
    apr_wait_how_e waithow
)

Wait for a child process to die The child’s 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.

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.

apr_status_t
apr_proc_wait_all_procs(
    apr_proc_t* proc,
    int* exitcode,
    apr_exit_why_e* exitwhy,
    apr_wait_how_e waithow,
    apr_pool_t* p
)

Wait for any current child process to die and return information about that child. Bug Passing proc as a *proc rather than **proc was an odd choice for some platforms… this should be revisited in 1.0

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.

apr_status_t
apr_proc_detach(int daemonize)

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.

void
apr_proc_other_child_register(
    apr_proc_t* proc,
    void(*)(int reason, void*, int status) maintenance,
    void* data,
    apr_file_t* write_fd,
    apr_pool_t* p
)

Register an other_child a child associated to its registered maintence callback. This callback is invoked when the process dies, is disconnected or disappears. 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.

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.

void
apr_proc_other_child_unregister(void* data)

Stop watching the specified other child.

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.

Parameters:

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

apr_status_t
apr_proc_other_child_alert(
    apr_proc_t* proc,
    int reason,
    int status
)

Notify the maintenance callback of a registered other child process that application has detected an event, such as death. An example of code using this behavior;

rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
if (:ref:`APR_STATUS_IS_CHILD_DONE(rv) <doxid-group___a_p_r___s_t_a_t_u_s___i_s_1ga1e6539dfa172cef4026105ca33b2b208>`) {
#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 ...]

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

void
apr_proc_other_child_refresh(
    apr_other_child_rec_t* ocr,
    int reason
)

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

void
apr_proc_other_child_refresh_all(int reason)

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

apr_status_t
apr_proc_kill(
    apr_proc_t* proc,
    int sig
)

Terminate a process.

Parameters:

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

void
apr_pool_note_subprocess(
    apr_pool_t* a,
    apr_proc_t* proc,
    apr_kill_conditions_e how
)

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

apr_status_t
apr_setup_signal_thread(void)

Setup the process for a single thread to be used for all signal handling.

Warning

This must be called before any threads are created

apr_status_t
apr_signal_thread(int(*)(int signum) signal_handler)

Make the current thread listen for signals. This thread will loop forever, calling a provided function whenever it receives a signal. That functions should return 1 if the signal has been handled, 0 otherwise.

Parameters:

signal_handler

The function to call when a signal is received apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))

apr_pool_t*
apr_thread_pool_get(const apr_thread_t* thethread)

Get the child-pool used by the thread from the thread info.

Returns:

apr_pool_t the pool

Macros

#define APR_CHILD_BLOCK

See also:

apr_procattr_io_set

#define APR_FULL_BLOCK

See also:

apr_procattr_io_set and apr_file_pipe_create_ex

#define APR_FULL_NONBLOCK

See also:

apr_procattr_io_set and apr_file_pipe_create_ex

#define APR_LIMIT_CPU

See also:

apr_procattr_limit_set

#define APR_LIMIT_MEM

See also:

apr_procattr_limit_set

#define APR_LIMIT_NOFILE

See also:

apr_procattr_limit_set

#define APR_LIMIT_NPROC

See also:

apr_procattr_limit_set

#define APR_NO_FILE

Note

Win32 only effective with version 1.2.12, portably introduced in 1.3.0

See also:

apr_procattr_io_set

apr_procattr_io_set

#define APR_NO_PIPE

See also:

apr_procattr_io_set

#define APR_PARENT_BLOCK

See also:

apr_procattr_io_set

#define APR_PROC_CHECK_CORE_DUMP(x)

did we get core

#define APR_PROC_CHECK_EXIT(x)

did we exit the process

#define APR_PROC_CHECK_SIGNALED(x)

did we get a signal

#define APR_PROC_DETACH_DAEMONIZE

Detach

#define APR_PROC_DETACH_FOREGROUND

Do not detach

#define APR_READ_BLOCK

See also:

apr_file_pipe_create_ex

#define APR_WRITE_BLOCK

See also:

apr_file_pipe_create_ex