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 #if APR_HAS_FORK 00533 /** 00534 * This is currently the only non-portable call in APR. This executes 00535 * a standard unix fork. 00536 * @param proc The resulting process handle. 00537 * @param cont The pool to use. 00538 * @remark returns APR_INCHILD for the child, and APR_INPARENT for the parent 00539 * or an error. 00540 */ 00541 APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont); 00542 #endif 00543 00544 /** 00545 * Create a new process and execute a new program within that process. 00546 * @param new_proc The resulting process handle. 00547 * @param progname The program to run 00548 * @param args the arguments to pass to the new program. The first 00549 * one should be the program name. 00550 * @param env The new environment table for the new process. This 00551 * should be a list of NULL-terminated strings. This argument 00552 * is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and 00553 * APR_SHELLCMD_ENV types of commands. 00554 * @param attr the procattr we should use to determine how to create the new 00555 * process 00556 * @param pool The pool to use. 00557 * @note This function returns without waiting for the new process to terminate; 00558 * use apr_proc_wait for that. 00559 */ 00560 APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc, 00561 const char *progname, 00562 const char * const *args, 00563 const char * const *env, 00564 apr_procattr_t *attr, 00565 apr_pool_t *pool); 00566 00567 /** 00568 * Wait for a child process to die 00569 * @param proc The process handle that corresponds to the desired child process 00570 * @param exitcode The returned exit status of the child, if a child process 00571 * dies, or the signal that caused the child to die. 00572 * On platforms that don't support obtaining this information, 00573 * the status parameter will be returned as APR_ENOTIMPL. 00574 * @param exitwhy Why the child died, the bitwise or of: 00575 * <PRE> 00576 * APR_PROC_EXIT -- process terminated normally 00577 * APR_PROC_SIGNAL -- process was killed by a signal 00578 * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and 00579 * generated a core dump. 00580 * </PRE> 00581 * @param waithow How should we wait. One of: 00582 * <PRE> 00583 * APR_WAIT -- block until the child process dies. 00584 * APR_NOWAIT -- return immediately regardless of if the 00585 * child is dead or not. 00586 * </PRE> 00587 * @remark The childs status is in the return code to this process. It is one of: 00588 * <PRE> 00589 * APR_CHILD_DONE -- child is no longer running. 00590 * APR_CHILD_NOTDONE -- child is still running. 00591 * </PRE> 00592 */ 00593 APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc, 00594 int *exitcode, apr_exit_why_e *exitwhy, 00595 apr_wait_how_e waithow); 00596 00597 /** 00598 * Wait for any current child process to die and return information 00599 * about that child. 00600 * @param proc Pointer to NULL on entry, will be filled out with child's 00601 * information 00602 * @param exitcode The returned exit status of the child, if a child process 00603 * dies, or the signal that caused the child to die. 00604 * On platforms that don't support obtaining this information, 00605 * the status parameter will be returned as APR_ENOTIMPL. 00606 * @param exitwhy Why the child died, the bitwise or of: 00607 * <PRE> 00608 * APR_PROC_EXIT -- process terminated normally 00609 * APR_PROC_SIGNAL -- process was killed by a signal 00610 * APR_PROC_SIGNAL_CORE -- process was killed by a signal, and 00611 * generated a core dump. 00612 * </PRE> 00613 * @param waithow How should we wait. One of: 00614 * <PRE> 00615 * APR_WAIT -- block until the child process dies. 00616 * APR_NOWAIT -- return immediately regardless of if the 00617 * child is dead or not. 00618 * </PRE> 00619 * @param p Pool to allocate child information out of. 00620 * @bug Passing proc as a *proc rather than **proc was an odd choice 00621 * for some platforms... this should be revisited in 1.0 00622 */ 00623 APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc, 00624 int *exitcode, 00625 apr_exit_why_e *exitwhy, 00626 apr_wait_how_e waithow, 00627 apr_pool_t *p); 00628 00629 #define APR_PROC_DETACH_FOREGROUND 0 /**< Do not detach */ 00630 #define APR_PROC_DETACH_DAEMONIZE 1 /**< Detach */ 00631 00632 /** 00633 * Detach the process from the controlling terminal. 00634 * @param daemonize set to non-zero if the process should daemonize 00635 * and become a background process, else it will 00636 * stay in the foreground. 00637 */ 00638 APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize); 00639 00640 /** 00641 * Register an other_child -- a child associated to its registered 00642 * maintence callback. This callback is invoked when the process 00643 * dies, is disconnected or disappears. 00644 * @param proc The child process to register. 00645 * @param maintenance maintenance is a function that is invoked with a 00646 * reason and the data pointer passed here. 00647 * @param data Opaque context data passed to the maintenance function. 00648 * @param write_fd An fd that is probed for writing. If it is ever unwritable 00649 * then the maintenance is invoked with reason 00650 * OC_REASON_UNWRITABLE. 00651 * @param p The pool to use for allocating memory. 00652 * @bug write_fd duplicates the proc->out stream, it's really redundant 00653 * and should be replaced in the APR 1.0 API with a bitflag of which 00654 * proc->in/out/err handles should be health checked. 00655 * @bug no platform currently tests the pipes health. 00656 */ 00657 APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 00658 void (*maintenance) (int reason, 00659 void *, 00660 int status), 00661 void *data, apr_file_t *write_fd, 00662 apr_pool_t *p); 00663 00664 /** 00665 * Stop watching the specified other child. 00666 * @param data The data to pass to the maintenance function. This is 00667 * used to find the process to unregister. 00668 * @warning Since this can be called by a maintenance function while we're 00669 * scanning the other_children list, all scanners should protect 00670 * themself by loading ocr->next before calling any maintenance 00671 * function. 00672 */ 00673 APR_DECLARE(void) apr_proc_other_child_unregister(void *data); 00674 00675 /** 00676 * Notify the maintenance callback of a registered other child process 00677 * that application has detected an event, such as death. 00678 * @param proc The process to check 00679 * @param reason The reason code to pass to the maintenance function 00680 * @param status The status to pass to the maintenance function 00681 * @remark An example of code using this behavior; 00682 * <pre> 00683 * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p); 00684 * if (APR_STATUS_IS_CHILD_DONE(rv)) { 00685 * #if APR_HAS_OTHER_CHILD 00686 * if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status) 00687 * == APR_SUCCESS) { 00688 * ; (already handled) 00689 * } 00690 * else 00691 * #endif 00692 * [... handling non-otherchild processes death ...] 00693 * </pre> 00694 */ 00695 APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 00696 int reason, 00697 int status); 00698 00699 /** 00700 * Test one specific other child processes and invoke the maintenance callback 00701 * with the appropriate reason code, if still running, or the appropriate reason 00702 * code if the process is no longer healthy. 00703 * @param ocr The registered other child 00704 * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running 00705 */ 00706 APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr, 00707 int reason); 00708 00709 /** 00710 * Test all registered other child processes and invoke the maintenance callback 00711 * with the appropriate reason code, if still running, or the appropriate reason 00712 * code if the process is no longer healthy. 00713 * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes 00714 */ 00715 APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason); 00716 00717 /** 00718 * Terminate a process. 00719 * @param proc The process to terminate. 00720 * @param sig How to kill the process. 00721 */ 00722 APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig); 00723 00724 /** 00725 * Register a process to be killed when a pool dies. 00726 * @param a The pool to use to define the processes lifetime 00727 * @param proc The process to register 00728 * @param how How to kill the process, one of: 00729 * <PRE> 00730 * APR_KILL_NEVER -- process is never sent any signals 00731 * APR_KILL_ALWAYS -- process is sent SIGKILL on apr_pool_t cleanup 00732 * APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL 00733 * APR_JUST_WAIT -- wait forever for the process to complete 00734 * APR_KILL_ONLY_ONCE -- send SIGTERM and then wait 00735 * </PRE> 00736 */ 00737 APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc, 00738 apr_kill_conditions_e how); 00739 00740 #if APR_HAS_THREADS 00741 00742 #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) 00743 00744 /** 00745 * Setup the process for a single thread to be used for all signal handling. 00746 * @warning This must be called before any threads are created 00747 */ 00748 APR_DECLARE(apr_status_t) apr_setup_signal_thread(void); 00749 00750 /** 00751 * Make the current thread listen for signals. This thread will loop 00752 * forever, calling a provided function whenever it receives a signal. That 00753 * functions should return 1 if the signal has been handled, 0 otherwise. 00754 * @param signal_handler The function to call when a signal is received 00755 * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum)) 00756 */ 00757 APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum)); 00758 00759 #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */ 00760 00761 /** 00762 * Get the child-pool used by the thread from the thread info. 00763 * @return apr_pool_t the pool 00764 */ 00765 APR_POOL_DECLARE_ACCESSOR(thread); 00766 00767 #endif /* APR_HAS_THREADS */ 00768 00769 /** @} */ 00770 00771 #ifdef __cplusplus 00772 } 00773 #endif 00774 00775 #endif /* ! APR_THREAD_PROC_H */ 00776