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