Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

apr_thread_proc.h

Go to the documentation of this file.
00001 /* Copyright 2000-2004 The Apache Software Foundation
00002  *
00003  * Licensed under the Apache License, Version 2.0 (the "License");
00004  * you may not use this file except in compliance with the License.
00005  * You may obtain a copy of the License at
00006  *
00007  *     http://www.apache.org/licenses/LICENSE-2.0
00008  *
00009  * Unless required by applicable law or agreed to in writing, software
00010  * distributed under the License is distributed on an "AS IS" BASIS,
00011  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012  * See the License for the specific language governing permissions and
00013  * limitations under the License.
00014  */
00015 
00016 #ifndef APR_THREAD_PROC_H
00017 #define APR_THREAD_PROC_H
00018 
00019 /**
00020  * @file apr_thread_proc.h
00021  * @brief APR Thread and Process Library
00022  */
00023 
00024 #include "apr.h"
00025 #include "apr_file_io.h"
00026 #include "apr_pools.h"
00027 #include "apr_errno.h"
00028 
00029 #if APR_HAVE_STRUCT_RLIMIT
00030 #include <sys/time.h>
00031 #include <sys/resource.h>
00032 #endif
00033 
00034 #ifdef __cplusplus
00035 extern "C" {
00036 #endif /* __cplusplus */
00037 
00038 /**
00039  * @defgroup apr_thread_proc Threads and Process Functions
00040  * @ingroup APR 
00041  * @{
00042  */
00043 
00044 typedef enum {
00045     APR_SHELLCMD,           /**< use the shell to invoke the program */
00046     APR_PROGRAM,            /**< invoke the program directly, no copied env */
00047     APR_PROGRAM_ENV,        /**< invoke the program, replicating our environment */
00048     APR_PROGRAM_PATH,       /**< find program on PATH, use our environment */
00049     APR_SHELLCMD_ENV        /**< use the shell to invoke the program,
00050                              *   replicating our environment
00051                              */
00052 } apr_cmdtype_e;
00053 
00054 typedef enum {
00055     APR_WAIT,           /**< wait for the specified process to finish */
00056     APR_NOWAIT          /**< do not wait -- just see if it has finished */
00057 } apr_wait_how_e;
00058 
00059 /* I am specifically calling out the values so that the macros below make
00060  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
00061  * I am doing more clear.  If you want to add more reasons to exit, continue
00062  * to use bitmasks.
00063  */
00064 typedef enum {
00065     APR_PROC_EXIT = 1,          /**< process exited normally */
00066     APR_PROC_SIGNAL = 2,        /**< process exited due to a signal */
00067     APR_PROC_SIGNAL_CORE = 4    /**< process exited and dumped a core file */
00068 } apr_exit_why_e;
00069 
00070 /** did we exit the process */
00071 #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
00072 /** did we get a signal */
00073 #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
00074 /** did we get core */
00075 #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
00076 
00077 /** @see apr_procattr_io_set */
00078 #define APR_NO_PIPE          0
00079 
00080 /** @see apr_procattr_io_set */
00081 #define APR_FULL_BLOCK       1
00082 /** @see apr_procattr_io_set */
00083 #define APR_FULL_NONBLOCK    2
00084 /** @see apr_procattr_io_set */
00085 #define APR_PARENT_BLOCK     3
00086 /** @see apr_procattr_io_set */
00087 #define APR_CHILD_BLOCK      4
00088 
00089 /** @see apr_procattr_limit_set */
00090 #define APR_LIMIT_CPU        0
00091 /** @see apr_procattr_limit_set */
00092 #define APR_LIMIT_MEM        1
00093 /** @see apr_procattr_limit_set */
00094 #define APR_LIMIT_NPROC      2
00095 /** @see apr_procattr_limit_set */
00096 #define APR_LIMIT_NOFILE     3
00097 
00098 /**
00099  * @defgroup APR_OC Other Child Flags
00100  * @{
00101  */
00102 #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
00103                                            * unregister still */
00104 #define APR_OC_REASON_UNWRITABLE    1     /**< write_fd is unwritable */
00105 #define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
00106                                            * any necessary cleanup (including
00107                                            * sending a special signal to child)
00108                                            */
00109 #define APR_OC_REASON_UNREGISTER    3     /**< unregister has been called, do
00110                                            * whatever is necessary (including
00111                                            * kill the child) */
00112 #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
00113                                            * us knowing ... buggy os? */
00114 #define APR_OC_REASON_RUNNING       5     /**< a health check is occuring, 
00115                                            * for most maintainence functions
00116                                            * this is a no-op.
00117                                            */
00118 /** @} */
00119 
00120 /** The APR process type */
00121 typedef struct apr_proc_t {
00122     /** The process ID */
00123     pid_t pid;
00124     /** Parent's side of pipe to child's stdin */
00125     apr_file_t *in;
00126     /** Parent's side of pipe to child's stdout */
00127     apr_file_t *out;
00128     /** Parent's side of pipe to child's stdouterr */
00129     apr_file_t *err;
00130 #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
00131     /** Diagnositics/debugging string of the command invoked for 
00132      *  this process [only present if APR_HAS_PROC_INVOKED is true]
00133      * @remark Only enabled on Win32 by default.
00134      * @bug This should either always or never be present in release
00135      * builds - since it breaks binary compatibility.  We may enable
00136      * it always in APR 1.0 yet leave it undefined in most cases.
00137      */
00138     char *invoked;
00139 #endif
00140 #if defined(WIN32) || defined(DOXYGEN)
00141     /** (Win32 only) Creator's handle granting access to the process
00142      * @remark This handle is closed and reset to NULL in every case
00143      * corresponding to a waitpid() on Unix which returns the exit status.
00144      * Therefore Win32 correspond's to Unix's zombie reaping characteristics
00145      * and avoids potential handle leaks.
00146      */
00147     HANDLE hproc;
00148 #endif
00149 } apr_proc_t;
00150 
00151 /**
00152  * The prototype for APR child errfn functions.  (See the description
00153  * of apr_procattr_child_errfn_set() for more information.)
00154  * It is passed the following parameters:
00155  * @param pool Pool associated with the apr_proc_t.  If your child
00156  *             error function needs user data, associate it with this
00157  *             pool.
00158  * @param err APR error code describing the error
00159  * @param description Text description of type of processing which failed
00160  */
00161 typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
00162                                  const char *description);
00163 
00164 /** Opaque Thread structure. */
00165 typedef struct apr_thread_t           apr_thread_t;
00166 
00167 /** Opaque Thread attributes structure. */
00168 typedef struct apr_threadattr_t       apr_threadattr_t;
00169 
00170 /** Opaque Process attributes structure. */
00171 typedef struct apr_procattr_t         apr_procattr_t;
00172 
00173 /** Opaque control variable for one-time atomic variables.  */
00174 typedef struct apr_thread_once_t      apr_thread_once_t;
00175 
00176 /** Opaque thread private address space. */
00177 typedef struct apr_threadkey_t        apr_threadkey_t;
00178 
00179 /** Opaque record of child process. */
00180 typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
00181 
00182 /**
00183  * The prototype for any APR thread worker functions.
00184  */
00185 typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
00186 
00187 typedef enum {
00188     APR_KILL_NEVER,             /**< process is never sent any signals */
00189     APR_KILL_ALWAYS,            /**< process is sent SIGKILL on apr_pool_t cleanup */
00190     APR_KILL_AFTER_TIMEOUT,     /**< SIGTERM, wait 3 seconds, SIGKILL */
00191     APR_JUST_WAIT,              /**< wait forever for the process to complete */
00192     APR_KILL_ONLY_ONCE          /**< send SIGTERM and then wait */
00193 } apr_kill_conditions_e;
00194 
00195 /* Thread Function definitions */
00196 
00197 #if APR_HAS_THREADS
00198 
00199 /**
00200  * Create and initialize a new threadattr variable
00201  * @param new_attr The newly created threadattr.
00202  * @param cont The pool to use
00203  */
00204 APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
00205                                                 apr_pool_t *cont);
00206 
00207 /**
00208  * Set if newly created threads should be created in detached state.
00209  * @param attr The threadattr to affect 
00210  * @param on Non-zero if detached threads should be created.
00211  */
00212 APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
00213                                                     apr_int32_t on);
00214 
00215 /**
00216  * Get the detach state for this threadattr.
00217  * @param attr The threadattr to reference
00218  * @return APR_DETACH if threads are to be detached, or APR_NOTDETACH
00219  * if threads are to be joinable. 
00220  */
00221 APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
00222 
00223 /**
00224  * Set the stack size of newly created threads.
00225  * @param attr The threadattr to affect 
00226  * @param stacksize The stack size in bytes
00227  */
00228 APR_DECLARE(apr_status_t) apr_threadattr_stacksize_set(apr_threadattr_t *attr,
00229                                                        apr_size_t stacksize);
00230 
00231 /**
00232  * Set the stack guard area size of newly created threads.
00233  * @param attr The threadattr to affect 
00234  * @param guardsize The stack guard area size in bytes
00235  * @note Thread library implementations commonly use a "guard area"
00236  * after each thread's stack which is not readable or writable such that
00237  * stack overflows cause a segfault; this consumes e.g. 4K of memory
00238  * and increases memory management overhead.  Setting the guard area
00239  * size to zero hence trades off reliable behaviour on stack overflow
00240  * for performance. */
00241 APR_DECLARE(apr_status_t) apr_threadattr_guardsize_set(apr_threadattr_t *attr,
00242                                                        apr_size_t guardsize);
00243 
00244 /**
00245  * Create a new thread of execution
00246  * @param new_thread The newly created thread handle.
00247  * @param attr The threadattr to use to determine how to create the thread
00248  * @param func The function to start the new thread in
00249  * @param data Any data to be passed to the starting function
00250  * @param cont The pool to use
00251  */
00252 APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
00253                                             apr_threadattr_t *attr, 
00254                                             apr_thread_start_t func, 
00255                                             void *data, apr_pool_t *cont);
00256 
00257 /**
00258  * stop the current thread
00259  * @param thd The thread to stop
00260  * @param retval The return value to pass back to any thread that cares
00261  */
00262 APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
00263                                           apr_status_t retval);
00264 
00265 /**
00266  * block until the desired thread stops executing.
00267  * @param retval The return value from the dead thread.
00268  * @param thd The thread to join
00269  */
00270 APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
00271                                           apr_thread_t *thd); 
00272 
00273 /**
00274  * force the current thread to yield the processor
00275  */
00276 APR_DECLARE(void) apr_thread_yield(void);
00277 
00278 /**
00279  * Initialize the control variable for apr_thread_once.  If this isn't
00280  * called, apr_initialize won't work.
00281  * @param control The control variable to initialize
00282  * @param p The pool to allocate data from.
00283  */
00284 APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
00285                                                apr_pool_t *p);
00286 
00287 /**
00288  * Run the specified function one time, regardless of how many threads
00289  * call it.
00290  * @param control The control variable.  The same variable should
00291  *                be passed in each time the function is tried to be
00292  *                called.  This is how the underlying functions determine
00293  *                if the function has ever been called before.
00294  * @param func The function to call.
00295  */
00296 APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
00297                                           void (*func)(void));
00298 
00299 /**
00300  * detach a thread
00301  * @param thd The thread to detach 
00302  */
00303 APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
00304 
00305 /**
00306  * Return the pool associated with the current thread.
00307  * @param data The user data associated with the thread.
00308  * @param key The key to associate with the data
00309  * @param thread The currently open thread.
00310  */
00311 APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
00312                                              apr_thread_t *thread);
00313 
00314 /**
00315  * Return the pool associated with the current thread.
00316  * @param data The user data to associate with the thread.
00317  * @param key The key to use for associating the data with the tread
00318  * @param cleanup The cleanup routine to use when the thread is destroyed.
00319  * @param thread The currently open thread.
00320  */
00321 APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
00322                                              apr_status_t (*cleanup) (void *),
00323                                              apr_thread_t *thread);
00324 
00325 /**
00326  * Create and initialize a new thread private address space
00327  * @param key The thread private handle.
00328  * @param dest The destructor to use when freeing the private memory.
00329  * @param cont The pool to use
00330  */
00331 APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
00332                                                     void (*dest)(void *),
00333                                                     apr_pool_t *cont);
00334 
00335 /**
00336  * Get a pointer to the thread private memory
00337  * @param new_mem The data stored in private memory 
00338  * @param key The handle for the desired thread private memory 
00339  */
00340 APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
00341                                                  apr_threadkey_t *key);
00342 
00343 /**
00344  * Set the data to be stored in thread private memory
00345  * @param priv The data to be stored in private memory 
00346  * @param key The handle for the desired thread private memory 
00347  */
00348 APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
00349                                                  apr_threadkey_t *key);
00350 
00351 /**
00352  * Free the thread private memory
00353  * @param key The handle for the desired thread private memory 
00354  */
00355 APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
00356 
00357 /**
00358  * Return the pool associated with the current threadkey.
00359  * @param data The user data associated with the threadkey.
00360  * @param key The key associated with the data
00361  * @param threadkey The currently open threadkey.
00362  */
00363 APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
00364                                                 apr_threadkey_t *threadkey);
00365 
00366 /**
00367  * Return the pool associated with the current threadkey.
00368  * @param data The data to set.
00369  * @param key The key to associate with the data.
00370  * @param cleanup The cleanup routine to use when the file is destroyed.
00371  * @param threadkey The currently open threadkey.
00372  */
00373 APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
00374                                                 apr_status_t (*cleanup) (void *),
00375                                                 apr_threadkey_t *threadkey);
00376 
00377 #endif
00378 
00379 /**
00380  * Create and initialize a new procattr variable
00381  * @param new_attr The newly created procattr. 
00382  * @param cont The pool to use
00383  */
00384 APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
00385                                                   apr_pool_t *cont);
00386 
00387 /**
00388  * Determine if any of stdin, stdout, or stderr should be linked to pipes 
00389  * when starting a child process.
00390  * @param attr The procattr we care about. 
00391  * @param in Should stdin be a pipe back to the parent?
00392  * @param out Should stdout be a pipe back to the parent?
00393  * @param err Should stderr be a pipe back to the parent?
00394  */
00395 APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
00396                                              apr_int32_t in, apr_int32_t out,
00397                                              apr_int32_t err);
00398 
00399 /**
00400  * Set the child_in and/or parent_in values to existing apr_file_t values.
00401  * @param attr The procattr we care about. 
00402  * @param child_in apr_file_t value to use as child_in. Must be a valid file.
00403  * @param parent_in apr_file_t value to use as parent_in. Must be a valid file.
00404  * @remark  This is NOT a required initializer function. This is
00405  *          useful if you have already opened a pipe (or multiple files)
00406  *          that you wish to use, perhaps persistently across multiple
00407  *          process invocations - such as a log file. You can save some 
00408  *          extra function calls by not creating your own pipe since this
00409  *          creates one in the process space for you.
00410  */
00411 APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
00412                                                   apr_file_t *child_in,
00413                                                   apr_file_t *parent_in);
00414 
00415 /**
00416  * Set the child_out and parent_out values to existing apr_file_t values.
00417  * @param attr The procattr we care about. 
00418  * @param child_out apr_file_t value to use as child_out. Must be a valid file.
00419  * @param parent_out apr_file_t value to use as parent_out. Must be a valid file.
00420  * @remark This is NOT a required initializer function. This is
00421  *         useful if you have already opened a pipe (or multiple files)
00422  *         that you wish to use, perhaps persistently across multiple
00423  *         process invocations - such as a log file. 
00424  */
00425 APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
00426                                                    apr_file_t *child_out,
00427                                                    apr_file_t *parent_out);
00428 
00429 /**
00430  * Set the child_err and parent_err values to existing apr_file_t values.
00431  * @param attr The procattr we care about. 
00432  * @param child_err apr_file_t value to use as child_err. Must be a valid file.
00433  * @param parent_err apr_file_t value to use as parent_err. Must be a valid file.
00434  * @remark This is NOT a required initializer function. This is
00435  *         useful if you have already opened a pipe (or multiple files)
00436  *         that you wish to use, perhaps persistently across multiple
00437  *         process invocations - such as a log file. 
00438  */
00439 APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
00440                                                    apr_file_t *child_err,
00441                                                    apr_file_t *parent_err);
00442 
00443 /**
00444  * Set which directory the child process should start executing in.
00445  * @param attr The procattr we care about. 
00446  * @param dir Which dir to start in.  By default, this is the same dir as
00447  *            the parent currently resides in, when the createprocess call
00448  *            is made. 
00449  */
00450 APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
00451                                               const char *dir);
00452 
00453 /**
00454  * Set what type of command the child process will call.
00455  * @param attr The procattr we care about. 
00456  * @param cmd The type of command.  One of:
00457  * <PRE>
00458  *            APR_SHELLCMD     --  Anything that the shell can handle
00459  *            APR_PROGRAM      --  Executable program   (default) 
00460  *            APR_PROGRAM_ENV  --  Executable program, copy environment
00461  *            APR_PROGRAM_PATH --  Executable program on PATH, copy env
00462  * </PRE>
00463  */
00464 APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
00465                                                   apr_cmdtype_e cmd);
00466 
00467 /**
00468  * Determine if the child should start in detached state.
00469  * @param attr The procattr we care about. 
00470  * @param detach Should the child start in detached state?  Default is no. 
00471  */
00472 APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
00473                                                  apr_int32_t detach);
00474 
00475 #if APR_HAVE_STRUCT_RLIMIT
00476 /**
00477  * Set the Resource Utilization limits when starting a new process.
00478  * @param attr The procattr we care about. 
00479  * @param what Which limit to set, one of:
00480  * <PRE>
00481  *                 APR_LIMIT_CPU
00482  *                 APR_LIMIT_MEM
00483  *                 APR_LIMIT_NPROC
00484  *                 APR_LIMIT_NOFILE
00485  * </PRE>
00486  * @param limit Value to set the limit to.
00487  */
00488 APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
00489                                                 apr_int32_t what,
00490                                                 struct rlimit *limit);
00491 #endif
00492 
00493 /**
00494  * Specify an error function to be called in the child process if APR
00495  * encounters an error in the child prior to running the specified program.
00496  * @param attr The procattr describing the child process to be created.
00497  * @param errfn The function to call in the child process.
00498  * @remark At the present time, it will only be called from apr_proc_create()
00499  *         on platforms where fork() is used.  It will never be called on other
00500  *         platforms, on those platforms apr_proc_create() will return the error
00501  *         in the parent process rather than invoke the callback in the now-forked
00502  *         child process.
00503  */
00504 APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr,
00505                                                        apr_child_errfn_t *errfn);
00506 
00507 /**
00508  * Specify that apr_proc_create() should do whatever it can to report
00509  * failures to the caller of apr_proc_create(), rather than find out in
00510  * the child.
00511  * @param attr The procattr describing the child process to be created.
00512  * @param chk Flag to indicate whether or not extra work should be done
00513  *            to try to report failures to the caller.
00514  * @remark This flag only affects apr_proc_create() on platforms where
00515  *         fork() is used.  This leads to extra overhead in the calling
00516  *         process, but that may help the application handle such
00517  *         errors more gracefully.
00518  */
00519 APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr,
00520                                                        apr_int32_t chk);
00521 
00522 /**
00523  * Determine if the child should start in its own address space or using the 
00524  * current one from its parent
00525  * @param attr The procattr we care about. 
00526  * @param addrspace Should the child start in its own address space?  Default
00527  *                  is no on NetWare and yes on other platforms.
00528  */
00529 APR_DECLARE(apr_status_t) apr_procattr_addrspace_set(apr_procattr_t *attr,
00530                                                        apr_int32_t addrspace);
00531 
00532 /**
00533  * Set the username used for running process
00534  * @param attr The procattr we care about. 
00535  * @param username The username used
00536  * @param password User password if needed. Password is needed on WIN32
00537  *                 or any other platform having
00538  *                 APR_PROCATTR_USER_SET_REQUIRES_PASSWORD set.
00539  */
00540 APR_DECLARE(apr_status_t) apr_procattr_user_set(apr_procattr_t *attr,
00541                                                 const char *username,
00542                                                 const char *password);
00543 
00544 /**
00545  * Set the group used for running process
00546  * @param attr The procattr we care about. 
00547  * @param groupname The group name  used
00548  */
00549 APR_DECLARE(apr_status_t) apr_procattr_group_set(apr_procattr_t *attr,
00550                                                  const char *groupname);
00551 
00552 
00553 #if APR_HAS_FORK
00554 /**
00555  * This is currently the only non-portable call in APR.  This executes 
00556  * a standard unix fork.
00557  * @param proc The resulting process handle. 
00558  * @param cont The pool to use. 
00559  * @remark returns APR_INCHILD for the child, and APR_INPARENT for the parent
00560  * or an error.
00561  */
00562 APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
00563 #endif
00564 
00565 /**
00566  * Create a new process and execute a new program within that process.
00567  * @param new_proc The resulting process handle.
00568  * @param progname The program to run 
00569  * @param args the arguments to pass to the new program.  The first 
00570  *             one should be the program name.
00571  * @param env The new environment table for the new process.  This 
00572  *            should be a list of NULL-terminated strings. This argument
00573  *            is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and
00574  *            APR_SHELLCMD_ENV types of commands.
00575  * @param attr the procattr we should use to determine how to create the new
00576  *         process
00577  * @param pool The pool to use.
00578  * @note This function returns without waiting for the new process to terminate;
00579  * use apr_proc_wait for that.
00580  */
00581 APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
00582                                           const char *progname,
00583                                           const char * const *args,
00584                                           const char * const *env, 
00585                                           apr_procattr_t *attr, 
00586                                           apr_pool_t *pool);
00587 
00588 /**
00589  * Wait for a child process to die
00590  * @param proc The process handle that corresponds to the desired child process 
00591  * @param exitcode The returned exit status of the child, if a child process 
00592  *                 dies, or the signal that caused the child to die.
00593  *                 On platforms that don't support obtaining this information, 
00594  *                 the status parameter will be returned as APR_ENOTIMPL.
00595  * @param exitwhy Why the child died, the bitwise or of:
00596  * <PRE>
00597  *            APR_PROC_EXIT         -- process terminated normally
00598  *            APR_PROC_SIGNAL       -- process was killed by a signal
00599  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
00600  *                                     generated a core dump.
00601  * </PRE>
00602  * @param waithow How should we wait.  One of:
00603  * <PRE>
00604  *            APR_WAIT   -- block until the child process dies.
00605  *            APR_NOWAIT -- return immediately regardless of if the 
00606  *                          child is dead or not.
00607  * </PRE>
00608  * @remark The childs status is in the return code to this process.  It is one of:
00609  * <PRE>
00610  *            APR_CHILD_DONE     -- child is no longer running.
00611  *            APR_CHILD_NOTDONE  -- child is still running.
00612  * </PRE>
00613  */
00614 APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
00615                                         int *exitcode, apr_exit_why_e *exitwhy,
00616                                         apr_wait_how_e waithow);
00617 
00618 /**
00619  * Wait for any current child process to die and return information 
00620  * about that child.
00621  * @param proc Pointer to NULL on entry, will be filled out with child's 
00622  *             information 
00623  * @param exitcode The returned exit status of the child, if a child process 
00624  *                 dies, or the signal that caused the child to die.
00625  *                 On platforms that don't support obtaining this information, 
00626  *                 the status parameter will be returned as APR_ENOTIMPL.
00627  * @param exitwhy Why the child died, the bitwise or of:
00628  * <PRE>
00629  *            APR_PROC_EXIT         -- process terminated normally
00630  *            APR_PROC_SIGNAL       -- process was killed by a signal
00631  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
00632  *                                     generated a core dump.
00633  * </PRE>
00634  * @param waithow How should we wait.  One of:
00635  * <PRE>
00636  *            APR_WAIT   -- block until the child process dies.
00637  *            APR_NOWAIT -- return immediately regardless of if the 
00638  *                          child is dead or not.
00639  * </PRE>
00640  * @param p Pool to allocate child information out of.
00641  * @bug Passing proc as a *proc rather than **proc was an odd choice
00642  * for some platforms... this should be revisited in 1.0
00643  */
00644 APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
00645                                                   int *exitcode,
00646                                                   apr_exit_why_e *exitwhy,
00647                                                   apr_wait_how_e waithow,
00648                                                   apr_pool_t *p);
00649 
00650 #define APR_PROC_DETACH_FOREGROUND 0    /**< Do not detach */
00651 #define APR_PROC_DETACH_DAEMONIZE 1     /**< Detach */
00652 
00653 /**
00654  * Detach the process from the controlling terminal.
00655  * @param daemonize set to non-zero if the process should daemonize
00656  *                  and become a background process, else it will
00657  *                  stay in the foreground.
00658  */
00659 APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
00660 
00661 /**
00662  * Register an other_child -- a child associated to its registered 
00663  * maintence callback.  This callback is invoked when the process
00664  * dies, is disconnected or disappears.
00665  * @param proc The child process to register.
00666  * @param maintenance maintenance is a function that is invoked with a 
00667  *                    reason and the data pointer passed here.
00668  * @param data Opaque context data passed to the maintenance function.
00669  * @param write_fd An fd that is probed for writing.  If it is ever unwritable
00670  *                 then the maintenance is invoked with reason 
00671  *                 OC_REASON_UNWRITABLE.
00672  * @param p The pool to use for allocating memory.
00673  * @bug write_fd duplicates the proc->out stream, it's really redundant
00674  * and should be replaced in the APR 1.0 API with a bitflag of which
00675  * proc->in/out/err handles should be health checked.
00676  * @bug no platform currently tests the pipes health.
00677  */
00678 APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 
00679                                            void (*maintenance) (int reason, 
00680                                                                 void *, 
00681                                                                 int status),
00682                                            void *data, apr_file_t *write_fd,
00683                                            apr_pool_t *p);
00684 
00685 /**
00686  * Stop watching the specified other child.  
00687  * @param data The data to pass to the maintenance function.  This is
00688  *             used to find the process to unregister.
00689  * @warning Since this can be called by a maintenance function while we're
00690  *          scanning the other_children list, all scanners should protect 
00691  *          themself by loading ocr->next before calling any maintenance 
00692  *          function.
00693  */
00694 APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
00695 
00696 /**
00697  * Notify the maintenance callback of a registered other child process
00698  * that application has detected an event, such as death.
00699  * @param proc The process to check
00700  * @param reason The reason code to pass to the maintenance function
00701  * @param status The status to pass to the maintenance function
00702  * @remark An example of code using this behavior;
00703  * <pre>
00704  * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
00705  * if (APR_STATUS_IS_CHILD_DONE(rv)) {
00706  * #if APR_HAS_OTHER_CHILD
00707  *     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
00708  *             == APR_SUCCESS) {
00709  *         ;  (already handled)
00710  *     }
00711  *     else
00712  * #endif
00713  *         [... handling non-otherchild processes death ...]
00714  * </pre>
00715  */
00716 APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 
00717                                                      int reason,
00718                                                      int status);
00719 
00720 /**
00721  * Test one specific other child processes and invoke the maintenance callback 
00722  * with the appropriate reason code, if still running, or the appropriate reason 
00723  * code if the process is no longer healthy.
00724  * @param ocr The registered other child
00725  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running
00726  */
00727 APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr,
00728                                                int reason);
00729 
00730 /**
00731  * Test all registered other child processes and invoke the maintenance callback 
00732  * with the appropriate reason code, if still running, or the appropriate reason 
00733  * code if the process is no longer healthy.
00734  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes
00735  */
00736 APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason);
00737 
00738 /** 
00739  * Terminate a process.
00740  * @param proc The process to terminate.
00741  * @param sig How to kill the process.
00742  */
00743 APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
00744 
00745 /**
00746  * Register a process to be killed when a pool dies.
00747  * @param a The pool to use to define the processes lifetime 
00748  * @param proc The process to register
00749  * @param how How to kill the process, one of:
00750  * <PRE>
00751  *         APR_KILL_NEVER         -- process is never sent any signals
00752  *         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
00753  *         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
00754  *         APR_JUST_WAIT          -- wait forever for the process to complete
00755  *         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
00756  * </PRE>
00757  */
00758 APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc,
00759                                            apr_kill_conditions_e how);
00760 
00761 #if APR_HAS_THREADS 
00762 
00763 #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
00764 
00765 /**
00766  * Setup the process for a single thread to be used for all signal handling.
00767  * @warning This must be called before any threads are created
00768  */
00769 APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
00770 
00771 /**
00772  * Make the current thread listen for signals.  This thread will loop
00773  * forever, calling a provided function whenever it receives a signal.  That
00774  * functions should return 1 if the signal has been handled, 0 otherwise.
00775  * @param signal_handler The function to call when a signal is received
00776  * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
00777  */
00778 APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
00779 
00780 #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
00781 
00782 /**
00783  * Get the child-pool used by the thread from the thread info.
00784  * @return apr_pool_t the pool
00785  */
00786 APR_POOL_DECLARE_ACCESSOR(thread);
00787 
00788 #endif /* APR_HAS_THREADS */
00789 
00790 /** @} */
00791 
00792 #ifdef __cplusplus
00793 }
00794 #endif
00795 
00796 #endif  /* ! APR_THREAD_PROC_H */
00797 

Generated on Tue May 10 04:16:54 2005 for Apache Portable Runtime by  doxygen 1.3.9.1