rbb 99/07/30 11:53:45
Modified: apr/threadproc/unix proc.c procsup.c thread.c threadcancel.c threadpriv.c Log: The final APR doc commit :) Revision Changes Path 1.21 +103 -0 apache-apr/apr/threadproc/unix/proc.c Index: proc.c =================================================================== RCS file: /home/cvs/apache-apr/apr/threadproc/unix/proc.c,v retrieving revision 1.20 retrieving revision 1.21 diff -u -r1.20 -r1.21 --- proc.c 1999/07/06 17:01:41 1.20 +++ proc.c 1999/07/30 18:53:39 1.21 @@ -66,6 +66,12 @@ #include <sys/wait.h> #include <unistd.h> +/* ***APRDOC******************************************************** + * ap_status_t ap_createprocattr_init(ap_context_t *, ap_procattr_t **) + * Create and initialize a new procattr variable + * arg 1) The context to use + * arg 2) The newly created procattr. + */ ap_status_t ap_createprocattr_init(ap_context_t *cont, struct procattr_t **new) { (*new) = (struct procattr_t *)ap_palloc(cont, @@ -86,6 +92,16 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_setprocattr_io(ap_procattr_t *, ap_int32_t, ap_int32_t + * ap_int32_t) + * Determine if any of stdin, stdout, or stderr should be linked + * to pipes when starting a child process. + * arg 1) The procattr we care about. + * arg 2) Should stdin be a pipe bnack to the parent? + * arg 3) Should stdout be a pipe bnack to the parent? + * arg 4) Should stderr be a pipe bnack to the parent? + */ ap_status_t ap_setprocattr_io(struct procattr_t *attr, ap_int32_t in, ap_int32_t out, ap_int32_t err) { @@ -111,6 +127,14 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_setprocattr_dir(ap_procattr_t *, char *) + * Set which directory the child process should start executing in. + * arg 1) The procattr we care about. + * arg 2) Which dir to start in. By default, this is the same dir as + * the parent currently resides in, when the createprocess call + * is made. + */ ap_status_t ap_setprocattr_dir(struct procattr_t *attr, char *dir) { @@ -121,6 +145,14 @@ return APR_ENOMEM; } +/* ***APRDOC******************************************************** + * ap_status_t ap_setprocattr_cmdtype(ap_procattr_t *, ap_cmdtype_e) + * Set what type of command the child process will call. + * arg 1) The procattr we care about. + * arg 2) The type of command. One of: + * APR_SHELLCMD -- Shell script + * APR_PROGRAM -- Executable program (default) + */ ap_status_t ap_setprocattr_cmdtype(struct procattr_t *attr, ap_cmdtype_e cmd) { @@ -128,12 +160,25 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_setprocattr_detach(ap_procattr_t *, ap_int32_t) + * Determine if the chlid should start in detached state. + * arg 1) The procattr we care about. + * arg 2) Should the child start in detached state? Default is no. + */ ap_status_t ap_setprocattr_detach(struct procattr_t *attr, ap_int32_t detach) { attr->detached = detach; return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_fork_detach(ap_context_t *, ap_proc_t **) + * This is currently the only non-portable call in APR. This executes + * a standard unix fork. + * arg 1) The context to use. + * arg 2) The resulting process handle. + */ ap_status_t ap_fork(ap_context_t *cont, struct proc_t **proc) { int pid; @@ -153,6 +198,20 @@ return APR_INPARENT; } +/* ***APRDOC******************************************************** + * ap_status_t ap_create_process(ap_context_t *, char *, char *const [], + char **, ap_procattr_t *, ap_proc_t **) + * Create a new process and execute a new program within that process. + * arg 1) The context to use. + * arg 2) The program to run + * arg 3) the arguments to pass to the new program. The first one should + * be the program name. + * arg 4) The new environment table for the new process. This should be a + * list of NULL-terminated strings. + * arg 5) the procattr we should use to determine how to create the new + * process + * arg 6) The resulting process handle. + */ ap_status_t ap_create_process(ap_context_t *cont, char *progname, char *const args[], char **env, struct procattr_t *attr, struct proc_t **new) @@ -240,24 +299,55 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_childin(ap_proc_t *, ap_file_t **) + * Get the file handle that is assocaited with a child's stdin. + * arg 1) The process handle that corresponds to the desired child process + * arg 2) The returned file handle. + */ ap_status_t ap_get_childin(struct proc_t *proc, ap_file_t **new) { (*new) = proc->attr->parent_in; return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_childout(ap_proc_t *, ap_file_t **) + * Get the file handle that is assocaited with a child's stdout. + * arg 1) The process handle that corresponds to the desired child process + * arg 2) The returned file handle. + */ ap_status_t ap_get_childout(struct proc_t *proc, ap_file_t **new) { (*new) = proc->attr->parent_out; return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_childerr(ap_proc_t *, ap_file_t **) + * Get the file handle that is assocaited with a child's stderr. + * arg 1) The process handle that corresponds to the desired child process + * arg 2) The returned file handle. + */ ap_status_t ap_get_childerr(struct proc_t *proc, ap_file_t **new) { (*new) = proc->attr->parent_err; return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_wait_proc(ap_proc_t *, ap_wait_how) + * Wait for a child process to die + * arg 1) The process handle that corresponds to the desired child process + * arg 2) 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. + * NOTE: 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. + */ ap_status_t ap_wait_proc(struct proc_t *proc, ap_wait_how_e wait) { @@ -282,6 +372,12 @@ return errno; } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_os_proc(ap_proc_t *, ap_os_proc_t *) + * convert the proc from os specific type to apr type. + * arg 1) The apr proc to converting + * arg 2) The os specific proc we are converting to + */ ap_status_t ap_get_os_proc(ap_proc_t *proc, ap_os_proc_t *theproc) { if (proc == NULL) { @@ -291,6 +387,13 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_put_os_proc(ap_context_t *, ap_proc_t *, ap_os_proc_t *) + * convert the proc from os specific type to apr type. + * arg 1) The context to use if it is needed. + * arg 2) The apr proc we are converting to. + * arg 3) The os specific proc to convert + */ ap_status_t ap_put_os_proc(ap_context_t *cont, struct proc_t **proc, ap_os_proc_t *theproc) { 1.4 +6 -0 apache-apr/apr/threadproc/unix/procsup.c Index: procsup.c =================================================================== RCS file: /home/cvs/apache-apr/apr/threadproc/unix/procsup.c,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- procsup.c 1999/07/13 19:51:39 1.3 +++ procsup.c 1999/07/30 18:53:40 1.4 @@ -62,6 +62,12 @@ #include "apr_general.h" #include "apr_lib.h" +/* ***APRDOC******************************************************** + * ap_status_t ap_detach(ap_context_t *, ap_proc_t *) + * Detach the process from the controlling terminal. + * arg 1) The context to use if it is needed. + * arg 2) The new process handler + */ ap_status_t ap_detach(ap_context_t *cont, struct proc_t **new) { int x; 1.13 +58 -0 apache-apr/apr/threadproc/unix/thread.c Index: thread.c =================================================================== RCS file: /home/cvs/apache-apr/apr/threadproc/unix/thread.c,v retrieving revision 1.12 retrieving revision 1.13 diff -u -r1.12 -r1.13 --- thread.c 1999/07/27 18:46:22 1.12 +++ thread.c 1999/07/30 18:53:40 1.13 @@ -59,6 +59,12 @@ #include "apr_portable.h" #ifdef HAVE_PTHREAD_H +/* ***APRDOC******************************************************** + * ap_status_t ap_create_threadattr(ap_context_t *, ap_threadattr_t **) + * Create and initialize a new threadattr variable + * arg 1) The context to use + * arg 2) The newly created threadattr. + */ ap_status_t ap_create_threadattr(ap_context_t *cont, struct threadattr_t **new) { ap_status_t stat; @@ -81,6 +87,12 @@ return stat; } +/* ***APRDOC******************************************************** + * ap_status_t ap_setthreadattr_detach(ap_threadattr_t *, ap_int32_t) + * Set if newly created threads should be created in detach mode. + * arg 1) The threadattr to affect + * arg 2) Thread detach state on or off + */ ap_status_t ap_setthreadattr_detach(struct threadattr_t *attr, ap_int32_t on) { ap_status_t stat; @@ -92,6 +104,12 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_getthreadattr_detach(ap_threadattr_t *, ap_int32_t *) + * Get the detach mode for this threadattr. + * arg 1) The threadattr to reference + * arg 2) Thread detach state on or off + */ ap_status_t ap_getthreadattr_detach(struct threadattr_t *attr) { int state; @@ -102,6 +120,16 @@ return APR_NOTDETACH; } +/* ***APRDOC******************************************************** + * ap_status_t ap_create_thread(ap_context_t *, ap_threadattr_t *, + * ap_thread_start_t, coid *, ap_thread_t **) + * Create a new thread of execution + * arg 1) The context to use + * arg 2) The threadattr to use to determine how to create the thread + * arg 3) The function to start the new thread in + * arg 4) Any data to be passed to the starting function + * arg 5) The newly created thread handle. + */ ap_status_t ap_create_thread(ap_context_t *cont, struct threadattr_t *attr, ap_thread_start_t func, void *data, struct thread_t **new) @@ -141,12 +169,24 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_thread_exit(ap_thread_t *, ap_status_t *) + * stop the current thread + * arg 1) The thread to stop + * arg 2) The return value to pass back to any thread that cares + */ ap_status_t ap_thread_exit(ap_thread_t *thd, ap_status_t *retval) { ap_destroy_pool(thd->cntxt); pthread_exit(retval); } +/* ***APRDOC******************************************************** + * ap_status_t ap_thread_join(ap_thread_t *, ap_status_t *) + * block until the desired thread stops executing. + * arg 1) The thread to join + * arg 2) The return value from the dead thread. + */ ap_status_t ap_thread_join(struct thread_t *thd, ap_status_t *retval) { ap_status_t stat; @@ -159,6 +199,11 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_thread_detach(ap_thread_t *) + * detach a thread + * arg 1) The thread to detach + */ ap_status_t ap_thread_detach(struct thread_t *thd) { ap_status_t stat; @@ -205,6 +250,12 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_os_thread(ap_thread_t *, ap_os_thread_t *) + * convert the thread to os specific type from apr type. + * arg 1) The apr thread to convert + * arg 2) The os specific thread we are converting to + */ ap_status_t ap_get_os_thread(struct thread_t *thd, ap_os_thread_t *thethd) { if (thd == NULL) { @@ -214,6 +265,13 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_put_os_thread(ap_context_t *, ap_thread_t *, ap_os_thread_t *) + * convert the thread from os specific type to apr type. + * arg 1) The context to use if it is needed. + * arg 2) The apr thread we are converting to. + * arg 3) The os specific thread to convert + */ ap_status_t ap_put_os_thread(ap_context_t *cont, struct thread_t **thd, ap_os_thread_t *thethd) { 1.6 +19 -0 apache-apr/apr/threadproc/unix/threadcancel.c Index: threadcancel.c =================================================================== RCS file: /home/cvs/apache-apr/apr/threadproc/unix/threadcancel.c,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- threadcancel.c 1999/07/27 18:46:23 1.5 +++ threadcancel.c 1999/07/30 18:53:40 1.6 @@ -58,6 +58,11 @@ #include "apr_general.h" #ifdef HAVE_PTHREAD_H +/* ***APRDOC******************************************************** + * ap_status_t ap_cancel_thread(ap_thread_t *) + * Asynchronously kill a thread + * arg 1) The thread to kill. + */ ap_status_t ap_cancel_thread(struct thread_t *thd) { ap_status_t stat; @@ -69,6 +74,14 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_setcanceltype(ap_context_t *, ap_int32_t) + * Determine how threads are cancelable. + * arg 1) The context to operate on + * arg 2) how are threads cancelable. One of: + * APR_CANCEL_ASYNCH -- cancel it no matter where it is + * APR_CANCEL_DEFER -- only cancel the thread if it is safe. + */ ap_status_t ap_setcanceltype(ap_context_t *cont, ap_int32_t type) { ap_status_t stat; @@ -80,6 +93,12 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_setcancelstate(ap_context_t *, ap_int32_t) + * Determine if threads will be cancelable. + * arg 1) The context to operate on + * arg 2) Are threads cancelable. + */ ap_status_t ap_setcancelstate(ap_context_t *cont, ap_int32_t type) { ap_status_t stat; 1.11 +40 -0 apache-apr/apr/threadproc/unix/threadpriv.c Index: threadpriv.c =================================================================== RCS file: /home/cvs/apache-apr/apr/threadproc/unix/threadpriv.c,v retrieving revision 1.10 retrieving revision 1.11 diff -u -r1.10 -r1.11 --- threadpriv.c 1999/07/27 18:46:23 1.10 +++ threadpriv.c 1999/07/30 18:53:41 1.11 @@ -60,6 +60,14 @@ #include "apr_portable.h" #ifdef HAVE_PTHREAD_H +/* ***APRDOC******************************************************** + * ap_status_t ap_create_thread_private(ap_context_t *, void *(void *), + * ap_key_t) + * Create and initialize a new thread private address space + * arg 1) The context to use + * arg 2) The destructor to use when freeing the private memory. + * arg 3) The thread private handle. + */ ap_status_t ap_create_thread_private(ap_context_t *cont, void (*dest)(void *), struct threadkey_t **key) { @@ -78,12 +86,24 @@ return stat; } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_thread_private(ap_key_t *, void **) + * Get a pointer to the thread private memory + * arg 1) The handle for the desired thread private memory + * arg 2) The data stored in private memory + */ ap_status_t ap_get_thread_private(struct threadkey_t *key, void **new) { (*new) = pthread_getspecific(key->key); return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_set_thread_private(ap_key_t *, void *) + * Set the data to be stored in thread private memory + * arg 1) The handle for the desired thread private memory + * arg 2) The data to be stored in private memory + */ ap_status_t ap_set_thread_private(struct threadkey_t *key, void *priv) { ap_status_t stat; @@ -95,6 +115,11 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_delete_thread_private(ap_key_t *) + * Free the thread private memory + * arg 1) The handle for the desired thread private memory + */ ap_status_t ap_delete_thread_private(struct threadkey_t *key) { ap_status_t stat; @@ -138,6 +163,13 @@ } } +/* ***APRDOC******************************************************** + * ap_status_t ap_get_os_threadkey(ap_key_t *, ap_os_threadkey_t *) + * convert the thread private memory key to os specific type + * from an apr type. + * arg 1) The apr handle we are converting from. + * arg 2) The os specific handle we are converting to. + */ ap_status_t ap_get_os_threadkey(struct threadkey_t *key, ap_os_threadkey_t *thekey) { if (key == NULL) { @@ -147,6 +179,14 @@ return APR_SUCCESS; } +/* ***APRDOC******************************************************** + * ap_status_t ap_put_os_threadkey(ap_context_t *, ap_key_t *, + * ap_os_threadkey_t *) + * convert the thread private memory key from os specific type to apr type. + * arg 1) The context to use if it is needed. + * arg 2) The apr handle we are converting to. + * arg 3) The os specific handle to convert + */ ap_status_t ap_put_os_threadkey(ap_context_t *cont, struct threadkey_t **key, ap_os_threadkey_t *thekey) {