apr_thread_proc.h

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

Generated on Mon Nov 26 11:23:52 2007 for Apache Portable Runtime by  doxygen 1.5.2