Apache Portable Runtime

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