home *** CD-ROM | disk | FTP | other *** search
/ Chip 2004 November / CMCD1104.ISO / Software / Complet / Apache / apache_2.0.52-win32-x86-no_ssl.msi / Data.Cab / F277238_apr_thread_proc.h < prev    next >
C/C++ Source or Header  |  2004-06-23  |  32KB  |  754 lines
  1. /* Copyright 2000-2004 The Apache Software Foundation
  2.  *
  3.  * Licensed under the Apache License, Version 2.0 (the "License");
  4.  * you may not use this file except in compliance with the License.
  5.  * You may obtain a copy of the License at
  6.  *
  7.  *     http://www.apache.org/licenses/LICENSE-2.0
  8.  *
  9.  * Unless required by applicable law or agreed to in writing, software
  10.  * distributed under the License is distributed on an "AS IS" BASIS,
  11.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12.  * See the License for the specific language governing permissions and
  13.  * limitations under the License.
  14.  */
  15.  
  16. #ifndef APR_THREAD_PROC_H
  17. #define APR_THREAD_PROC_H
  18.  
  19. /**
  20.  * @file apr_thread_proc.h
  21.  * @brief APR Thread and Process Library
  22.  */
  23.  
  24. #include "apr.h"
  25. #include "apr_file_io.h"
  26. #include "apr_pools.h"
  27. #include "apr_errno.h"
  28.  
  29. #if APR_HAVE_STRUCT_RLIMIT
  30. #include <sys/time.h>
  31. #include <sys/resource.h>
  32. #endif
  33.  
  34. #ifdef __cplusplus
  35. extern "C" {
  36. #endif /* __cplusplus */
  37.  
  38. /**
  39.  * @defgroup apr_thread_proc Threads and Process Functions
  40.  * @ingroup APR 
  41.  * @{
  42.  */
  43.  
  44. typedef enum {
  45.     APR_SHELLCMD,       /**< use the shell to invoke the program */
  46.     APR_PROGRAM,        /**< invoke the program directly, no copied env */
  47.     APR_PROGRAM_ENV,    /**< invoke the program, replicating our environment */
  48.     APR_PROGRAM_PATH,   /**< find program on PATH, use our environment */
  49.     APR_SHELLCMD_ENV    /**< use the shell to invoke the program,
  50.                           *   replicating our environment
  51.                           */
  52. } apr_cmdtype_e;
  53.  
  54. typedef enum {
  55.     APR_WAIT,           /**< wait for the specified process to finish */
  56.     APR_NOWAIT          /**< do not wait -- just see if it has finished */
  57. } apr_wait_how_e;
  58.  
  59. /* I am specifically calling out the values so that the macros below make
  60.  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
  61.  * I am doing more clear.  If you want to add more reasons to exit, continue
  62.  * to use bitmasks.
  63.  */
  64. typedef enum {
  65.     APR_PROC_EXIT = 1,          /**< process exited normally */
  66.     APR_PROC_SIGNAL = 2,        /**< process exited due to a signal */
  67.     APR_PROC_SIGNAL_CORE = 4    /**< process exited and dumped a core file */
  68. } apr_exit_why_e;
  69.  
  70. /** did we exit the process */
  71. #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
  72. /** did we get a signal */
  73. #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
  74. /** did we get core */
  75. #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
  76.  
  77. /** @see apr_procattr_io_set */
  78. #define APR_NO_PIPE          0
  79.  
  80. /** @see apr_procattr_io_set */
  81. #define APR_FULL_BLOCK       1
  82. /** @see apr_procattr_io_set */
  83. #define APR_FULL_NONBLOCK    2
  84. /** @see apr_procattr_io_set */
  85. #define APR_PARENT_BLOCK     3
  86. /** @see apr_procattr_io_set */
  87. #define APR_CHILD_BLOCK      4
  88.  
  89. /** @see apr_procattr_limit_set */
  90. #define APR_LIMIT_CPU        0
  91. /** @see apr_procattr_limit_set */
  92. #define APR_LIMIT_MEM        1
  93. /** @see apr_procattr_limit_set */
  94. #define APR_LIMIT_NPROC      2
  95. /** @see apr_procattr_limit_set */
  96. #define APR_LIMIT_NOFILE     3
  97.  
  98. /**
  99.  * @defgroup APR_OC Other Child Flags
  100.  * @{
  101.  */
  102. #define APR_OC_REASON_DEATH         0     /**< child has died, caller must call
  103.                                            * unregister still */
  104. #define APR_OC_REASON_UNWRITABLE    1     /**< write_fd is unwritable */
  105. #define APR_OC_REASON_RESTART       2     /**< a restart is occuring, perform
  106.                                            * any necessary cleanup (including
  107.                                            * sending a special signal to child)
  108.                                            */
  109. #define APR_OC_REASON_UNREGISTER    3     /**< unregister has been called, do
  110.                                            * whatever is necessary (including
  111.                                            * kill the child) */
  112. #define APR_OC_REASON_LOST          4     /**< somehow the child exited without
  113.                                            * us knowing ... buggy os? */
  114. #define APR_OC_REASON_RUNNING       5     /**< a health check is occuring, 
  115.                                            * for most maintainence functions
  116.                                            * this is a no-op.
  117.                                            */
  118. /** @} */
  119.  
  120. /** The APR process type */
  121. typedef struct apr_proc_t {
  122.     /** The process ID */
  123.     pid_t pid;
  124.     /** Parent's side of pipe to child's stdin */
  125.     apr_file_t *in;
  126.     /** Parent's side of pipe to child's stdout */
  127.     apr_file_t *out;
  128.     /** Parent's side of pipe to child's stdouterr */
  129.     apr_file_t *err;
  130. #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
  131.     /** Diagnositics/debugging string of the command invoked for 
  132.      *  this process [only present if APR_HAS_PROC_INVOKED is true]
  133.      * @remark Only enabled on Win32 by default.
  134.      * @bug This should either always or never be present in release
  135.      * builds - since it breaks binary compatibility.  We may enable
  136.      * it always in APR 1.0 yet leave it undefined in most cases.
  137.      */
  138.     char *invoked;
  139. #endif
  140. #if defined(WIN32) || defined(DOXYGEN)
  141.     /** (Win32 only) Creator's handle granting access to the process
  142.      * @remark This handle is closed and reset to NULL in every case
  143.      * corresponding to a waitpid() on Unix which returns the exit status.
  144.      * Therefore Win32 correspond's to Unix's zombie reaping characteristics
  145.      * and avoids potential handle leaks.
  146.      */
  147.     HANDLE hproc;
  148. #endif
  149. } apr_proc_t;
  150.  
  151. /**
  152.  * The prototype for APR child errfn functions.  (See the description
  153.  * of apr_procattr_child_errfn_set() for more information.)
  154.  * It is passed the following parameters:
  155.  * @param pool Pool associated with the apr_proc_t.  If your child
  156.  *             error function needs user data, associate it with this
  157.  *             pool.
  158.  * @param err APR error code describing the error
  159.  * @param description Text description of type of processing which failed
  160.  */
  161. typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
  162.                                  const char *description);
  163.  
  164. /** Opaque Thread structure. */
  165. typedef struct apr_thread_t           apr_thread_t;
  166.  
  167. /** Opaque Thread attributes structure. */
  168. typedef struct apr_threadattr_t       apr_threadattr_t;
  169.  
  170. /** Opaque Process attributes structure. */
  171. typedef struct apr_procattr_t         apr_procattr_t;
  172.  
  173. /** Opaque control variable for one-time atomic variables.  */
  174. typedef struct apr_thread_once_t      apr_thread_once_t;
  175.  
  176. /** Opaque thread private address space. */
  177. typedef struct apr_threadkey_t        apr_threadkey_t;
  178.  
  179. /** Opaque record of child process. */
  180. typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
  181.  
  182. /**
  183.  * The prototype for any APR thread worker functions.
  184.  */
  185. typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
  186.  
  187. typedef enum {
  188.     APR_KILL_NEVER,             /**< process is never sent any signals */
  189.     APR_KILL_ALWAYS,            /**< process is sent SIGKILL on apr_pool_t cleanup */
  190.     APR_KILL_AFTER_TIMEOUT,     /**< SIGTERM, wait 3 seconds, SIGKILL */
  191.     APR_JUST_WAIT,              /**< wait forever for the process to complete */
  192.     APR_KILL_ONLY_ONCE          /**< send SIGTERM and then wait */
  193. } apr_kill_conditions_e;
  194.  
  195. /* Thread Function definitions */
  196.  
  197. #if APR_HAS_THREADS
  198.  
  199. /**
  200.  * Create and initialize a new threadattr variable
  201.  * @param new_attr The newly created threadattr.
  202.  * @param cont The pool to use
  203.  */
  204. APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
  205.                                                 apr_pool_t *cont);
  206.  
  207. /**
  208.  * Set if newly created threads should be created in detached state.
  209.  * @param attr The threadattr to affect 
  210.  * @param on Thread detach state on or off
  211.  */
  212. APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
  213.                                                    apr_int32_t on);
  214.  
  215. /**
  216.  * Get the detach state for this threadattr.
  217.  * @param attr The threadattr to reference 
  218.  */
  219. APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
  220.  
  221. /**
  222.  * Create a new thread of execution
  223.  * @param new_thread The newly created thread handle.
  224.  * @param attr The threadattr to use to determine how to create the thread
  225.  * @param func The function to start the new thread in
  226.  * @param data Any data to be passed to the starting function
  227.  * @param cont The pool to use
  228.  */
  229. APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
  230.                                             apr_threadattr_t *attr, 
  231.                                             apr_thread_start_t func, 
  232.                                             void *data, apr_pool_t *cont);
  233.  
  234. /**
  235.  * stop the current thread
  236.  * @param thd The thread to stop
  237.  * @param retval The return value to pass back to any thread that cares
  238.  */
  239. APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
  240.                                           apr_status_t retval);
  241.  
  242. /**
  243.  * block until the desired thread stops executing.
  244.  * @param retval The return value from the dead thread.
  245.  * @param thd The thread to join
  246.  */
  247. APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
  248.                                           apr_thread_t *thd); 
  249.  
  250. /**
  251.  * force the current thread to yield the processor
  252.  */
  253. APR_DECLARE(void) apr_thread_yield(void);
  254.  
  255. /**
  256.  * Initialize the control variable for apr_thread_once.  If this isn't
  257.  * called, apr_initialize won't work.
  258.  * @param control The control variable to initialize
  259.  * @param p The pool to allocate data from.
  260.  */
  261. APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
  262.                                                apr_pool_t *p);
  263.  
  264. /**
  265.  * Run the specified function one time, regardless of how many threads
  266.  * call it.
  267.  * @param control The control variable.  The same variable should
  268.  *                be passed in each time the function is tried to be
  269.  *                called.  This is how the underlying functions determine
  270.  *                if the function has ever been called before.
  271.  * @param func The function to call.
  272.  */
  273. APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
  274.                                           void (*func)(void));
  275.  
  276. /**
  277.  * detach a thread
  278.  * @param thd The thread to detach 
  279.  */
  280. APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
  281.  
  282. /**
  283.  * Return the pool associated with the current thread.
  284.  * @param data The user data associated with the thread.
  285.  * @param key The key to associate with the data
  286.  * @param thread The currently open thread.
  287.  */
  288. APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
  289.                                              apr_thread_t *thread);
  290.  
  291. /**
  292.  * Return the pool associated with the current thread.
  293.  * @param data The user data to associate with the thread.
  294.  * @param key The key to use for associating the data with the tread
  295.  * @param cleanup The cleanup routine to use when the thread is destroyed.
  296.  * @param thread The currently open thread.
  297.  */
  298. APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
  299.                                              apr_status_t (*cleanup) (void *),
  300.                                              apr_thread_t *thread);
  301.  
  302. /**
  303.  * Create and initialize a new thread private address space
  304.  * @param key The thread private handle.
  305.  * @param dest The destructor to use when freeing the private memory.
  306.  * @param cont The pool to use
  307.  */
  308. APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
  309.                                                     void (*dest)(void *),
  310.                                                     apr_pool_t *cont);
  311.  
  312. /**
  313.  * Get a pointer to the thread private memory
  314.  * @param new_mem The data stored in private memory 
  315.  * @param key The handle for the desired thread private memory 
  316.  */
  317. APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
  318.                                                  apr_threadkey_t *key);
  319.  
  320. /**
  321.  * Set the data to be stored in thread private memory
  322.  * @param priv The data to be stored in private memory 
  323.  * @param key The handle for the desired thread private memory 
  324.  */
  325. APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
  326.                                                  apr_threadkey_t *key);
  327.  
  328. /**
  329.  * Free the thread private memory
  330.  * @param key The handle for the desired thread private memory 
  331.  */
  332. APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
  333.  
  334. /**
  335.  * Return the pool associated with the current threadkey.
  336.  * @param data The user data associated with the threadkey.
  337.  * @param key The key associated with the data
  338.  * @param threadkey The currently open threadkey.
  339.  */
  340. APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
  341.                                                 apr_threadkey_t *threadkey);
  342.  
  343. /**
  344.  * Return the pool associated with the current threadkey.
  345.  * @param data The data to set.
  346.  * @param key The key to associate with the data.
  347.  * @param cleanup The cleanup routine to use when the file is destroyed.
  348.  * @param threadkey The currently open threadkey.
  349.  */
  350. APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
  351.                                                 apr_status_t (*cleanup) (void *),
  352.                                                 apr_threadkey_t *threadkey);
  353.  
  354. #endif
  355.  
  356. /**
  357.  * Create and initialize a new procattr variable
  358.  * @param new_attr The newly created procattr. 
  359.  * @param cont The pool to use
  360.  */
  361. APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
  362.                                                   apr_pool_t *cont);
  363.  
  364. /**
  365.  * Determine if any of stdin, stdout, or stderr should be linked to pipes 
  366.  * when starting a child process.
  367.  * @param attr The procattr we care about. 
  368.  * @param in Should stdin be a pipe back to the parent?
  369.  * @param out Should stdout be a pipe back to the parent?
  370.  * @param err Should stderr be a pipe back to the parent?
  371.  */
  372. APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
  373.                                              apr_int32_t in, apr_int32_t out,
  374.                                              apr_int32_t err);
  375.  
  376. /**
  377.  * Set the child_in and/or parent_in values to existing apr_file_t values.
  378.  * @param attr The procattr we care about. 
  379.  * @param child_in apr_file_t value to use as child_in. Must be a valid file.
  380.  * @param parent_in apr_file_t value to use as parent_in. Must be a valid file.
  381.  * @remark  This is NOT a required initializer function. This is
  382.  *          useful if you have already opened a pipe (or multiple files)
  383.  *          that you wish to use, perhaps persistently across multiple
  384.  *          process invocations - such as a log file. You can save some 
  385.  *          extra function calls by not creating your own pipe since this
  386.  *          creates one in the process space for you.
  387.  */
  388. APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
  389.                                                   apr_file_t *child_in,
  390.                                                   apr_file_t *parent_in);
  391.  
  392. /**
  393.  * Set the child_out and parent_out values to existing apr_file_t values.
  394.  * @param attr The procattr we care about. 
  395.  * @param child_out apr_file_t value to use as child_out. Must be a valid file.
  396.  * @param parent_out apr_file_t value to use as parent_out. Must be a valid file.
  397.  * @remark This is NOT a required initializer function. This is
  398.  *         useful if you have already opened a pipe (or multiple files)
  399.  *         that you wish to use, perhaps persistently across multiple
  400.  *         process invocations - such as a log file. 
  401.  */
  402. APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
  403.                                                    apr_file_t *child_out,
  404.                                                    apr_file_t *parent_out);
  405.  
  406. /**
  407.  * Set the child_err and parent_err values to existing apr_file_t values.
  408.  * @param attr The procattr we care about. 
  409.  * @param child_err apr_file_t value to use as child_err. Must be a valid file.
  410.  * @param parent_err apr_file_t value to use as parent_err. Must be a valid file.
  411.  * @remark This is NOT a required initializer function. This is
  412.  *         useful if you have already opened a pipe (or multiple files)
  413.  *         that you wish to use, perhaps persistently across multiple
  414.  *         process invocations - such as a log file. 
  415.  */
  416. APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
  417.                                                    apr_file_t *child_err,
  418.                                                    apr_file_t *parent_err);
  419.  
  420. /**
  421.  * Set which directory the child process should start executing in.
  422.  * @param attr The procattr we care about. 
  423.  * @param dir Which dir to start in.  By default, this is the same dir as
  424.  *            the parent currently resides in, when the createprocess call
  425.  *            is made. 
  426.  */
  427. APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
  428.                                               const char *dir);
  429.  
  430. /**
  431.  * Set what type of command the child process will call.
  432.  * @param attr The procattr we care about. 
  433.  * @param cmd The type of command.  One of:
  434.  * <PRE>
  435.  *            APR_SHELLCMD     --  Anything that the shell can handle
  436.  *            APR_PROGRAM      --  Executable program   (default) 
  437.  *            APR_PROGRAM_ENV  --  Executable program, copy environment
  438.  *            APR_PROGRAM_PATH --  Executable program on PATH, copy env
  439.  * </PRE>
  440.  */
  441. APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
  442.                                                   apr_cmdtype_e cmd);
  443.  
  444. /**
  445.  * Determine if the child should start in detached state.
  446.  * @param attr The procattr we care about. 
  447.  * @param detach Should the child start in detached state?  Default is no. 
  448.  */
  449. APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
  450.                                                  apr_int32_t detach);
  451.  
  452. #if APR_HAVE_STRUCT_RLIMIT
  453. /**
  454.  * Set the Resource Utilization limits when starting a new process.
  455.  * @param attr The procattr we care about. 
  456.  * @param what Which limit to set, one of:
  457.  * <PRE>
  458.  *                 APR_LIMIT_CPU
  459.  *                 APR_LIMIT_MEM
  460.  *                 APR_LIMIT_NPROC
  461.  *                 APR_LIMIT_NOFILE
  462.  * </PRE>
  463.  * @param limit Value to set the limit to.
  464.  */
  465. APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
  466.                                                 apr_int32_t what,
  467.                                                 struct rlimit *limit);
  468. #endif
  469.  
  470. /**
  471.  * Specify an error function to be called in the child process if APR
  472.  * encounters an error in the child prior to running the specified program.
  473.  * @param attr The procattr describing the child process to be created.
  474.  * @param errfn The function to call in the child process.
  475.  * @remark At the present time, it will only be called from apr_proc_create()
  476.  *         on platforms where fork() is used.  It will never be called on other
  477.  *         platforms, on those platforms apr_proc_create() will return the error
  478.  *         in the parent process rather than invoke the callback in the now-forked
  479.  *         child process.
  480.  */
  481. APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr,
  482.                                                        apr_child_errfn_t *errfn);
  483.  
  484. /**
  485.  * Specify that apr_proc_create() should do whatever it can to report
  486.  * failures to the caller of apr_proc_create(), rather than find out in
  487.  * the child.
  488.  * @param attr The procattr describing the child process to be created.
  489.  * @param chk Flag to indicate whether or not extra work should be done
  490.  *            to try to report failures to the caller.
  491.  * @remark This flag only affects apr_proc_create() on platforms where
  492.  *         fork() is used.  This leads to extra overhead in the calling
  493.  *         process, but that may help the application handle such
  494.  *         errors more gracefully.
  495.  */
  496. APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr,
  497.                                                        apr_int32_t chk);
  498.  
  499. #if APR_HAS_FORK
  500. /**
  501.  * This is currently the only non-portable call in APR.  This executes 
  502.  * a standard unix fork.
  503.  * @param proc The resulting process handle. 
  504.  * @param cont The pool to use. 
  505.  */
  506. APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
  507. #endif
  508.  
  509. /**
  510.  * Create a new process and execute a new program within that process.
  511.  * @param new_proc The resulting process handle.
  512.  * @param progname The program to run 
  513.  * @param args the arguments to pass to the new program.  The first 
  514.  *             one should be the program name.
  515.  * @param env The new environment table for the new process.  This 
  516.  *            should be a list of NULL-terminated strings. This argument
  517.  *            is ignored for APR_PROGRAM_ENV, APR_PROGRAM_PATH, and
  518.  *            APR_SHELLCMD_ENV types of commands.
  519.  * @param attr the procattr we should use to determine how to create the new
  520.  *         process
  521.  * @param cont The pool to use. 
  522.  */
  523. APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
  524.                                              const char *progname,
  525.                                              const char * const *args,
  526.                                              const char * const *env, 
  527.                                              apr_procattr_t *attr, 
  528.                                              apr_pool_t *cont);
  529.  
  530. /**
  531.  * Wait for a child process to die
  532.  * @param proc The process handle that corresponds to the desired child process 
  533.  * @param exitcode The returned exit status of the child, if a child process 
  534.  *                 dies, or the signal that caused the child to die.
  535.  *                 On platforms that don't support obtaining this information, 
  536.  *                 the status parameter will be returned as APR_ENOTIMPL.
  537.  * @param exitwhy Why the child died, the bitwise or of:
  538.  * <PRE>
  539.  *            APR_PROC_EXIT         -- process terminated normally
  540.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  541.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  542.  *                                     generated a core dump.
  543.  * </PRE>
  544.  * @param waithow How should we wait.  One of:
  545.  * <PRE>
  546.  *            APR_WAIT   -- block until the child process dies.
  547.  *            APR_NOWAIT -- return immediately regardless of if the 
  548.  *                          child is dead or not.
  549.  * </PRE>
  550.  * @remark The childs status is in the return code to this process.  It is one of:
  551.  * <PRE>
  552.  *            APR_CHILD_DONE     -- child is no longer running.
  553.  *            APR_CHILD_NOTDONE  -- child is still running.
  554.  * </PRE>
  555.  */
  556. APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
  557.                                         int *exitcode, apr_exit_why_e *exitwhy,
  558.                                         apr_wait_how_e waithow);
  559.  
  560. /**
  561.  * Wait for any current child process to die and return information 
  562.  * about that child.
  563.  * @param proc Pointer to NULL on entry, will be filled out with child's 
  564.  *             information 
  565.  * @param exitcode The returned exit status of the child, if a child process 
  566.  *                 dies, or the signal that caused the child to die.
  567.  *                 On platforms that don't support obtaining this information, 
  568.  *                 the status parameter will be returned as APR_ENOTIMPL.
  569.  * @param exitwhy Why the child died, the bitwise or of:
  570.  * <PRE>
  571.  *            APR_PROC_EXIT         -- process terminated normally
  572.  *            APR_PROC_SIGNAL       -- process was killed by a signal
  573.  *            APR_PROC_SIGNAL_CORE  -- process was killed by a signal, and
  574.  *                                     generated a core dump.
  575.  * </PRE>
  576.  * @param waithow How should we wait.  One of:
  577.  * <PRE>
  578.  *            APR_WAIT   -- block until the child process dies.
  579.  *            APR_NOWAIT -- return immediately regardless of if the 
  580.  *                          child is dead or not.
  581.  * </PRE>
  582.  * @param p Pool to allocate child information out of.
  583.  * @bug Passing proc as a *proc rather than **proc was an odd choice
  584.  * for some platforms... this should be revisited in 1.0
  585.  */
  586. APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
  587.                                                   int *exitcode,
  588.                                                   apr_exit_why_e *exitwhy,
  589.                                                   apr_wait_how_e waithow,
  590.                                                   apr_pool_t *p);
  591.  
  592. #define APR_PROC_DETACH_FOREGROUND 0    /**< Do not detach */
  593. #define APR_PROC_DETACH_DAEMONIZE 1     /**< Detach */
  594.  
  595. /**
  596.  * Detach the process from the controlling terminal.
  597.  * @param daemonize set to non-zero if the process should daemonize
  598.  *                  and become a background process, else it will
  599.  *                  stay in the foreground.
  600.  */
  601. APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
  602.  
  603. /**
  604.  * Register an other_child -- a child associated to its registered 
  605.  * maintence callback.  This callback is invoked when the process
  606.  * dies, is disconnected or disappears.
  607.  * @param proc The child process to register.
  608.  * @param maintenance maintenance is a function that is invoked with a 
  609.  *                    reason and the data pointer passed here.
  610.  * @param data Opaque context data passed to the maintenance function.
  611.  * @param write_fd An fd that is probed for writing.  If it is ever unwritable
  612.  *                 then the maintenance is invoked with reason 
  613.  *                 OC_REASON_UNWRITABLE.
  614.  * @param p The pool to use for allocating memory.
  615.  * @bug write_fd duplicates the proc->out stream, it's really redundant
  616.  * and should be replaced in the APR 1.0 API with a bitflag of which
  617.  * proc->in/out/err handles should be health checked.
  618.  * @bug no platform currently tests the pipes health.
  619.  */
  620. APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 
  621.                                            void (*maintenance) (int reason, 
  622.                                                                 void *, 
  623.                                                                 int status),
  624.                                            void *data, apr_file_t *write_fd,
  625.                                            apr_pool_t *p);
  626.  
  627. /**
  628.  * Stop watching the specified other child.  
  629.  * @param data The data to pass to the maintenance function.  This is
  630.  *             used to find the process to unregister.
  631.  * @warning Since this can be called by a maintenance function while we're
  632.  *          scanning the other_children list, all scanners should protect 
  633.  *          themself by loading ocr->next before calling any maintenance 
  634.  *          function.
  635.  */
  636. APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
  637.  
  638. /**
  639.  * Notify the maintenance callback of a registered other child process
  640.  * that application has detected an event, such as death.
  641.  * @param proc The process to check
  642.  * @param reason The reason code to pass to the maintenance function
  643.  * @param status The status to pass to the maintenance function
  644.  * @remark An example of code using this behavior;
  645.  * <pre>
  646.  * rv = apr_proc_wait_all_procs(&proc, &exitcode, &status, APR_WAIT, p);
  647.  * if (APR_STATUS_IS_CHILD_DONE(rv)) {
  648.  * #if APR_HAS_OTHER_CHILD
  649.  *     if (apr_proc_other_child_alert(&proc, APR_OC_REASON_DEATH, status)
  650.  *             == APR_SUCCESS) {
  651.  *         ;  (already handled)
  652.  *     }
  653.  *     else
  654.  * #endif
  655.  *         [... handling non-otherchild processes death ...]
  656.  * </pre>
  657.  */
  658. APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 
  659.                                                      int reason,
  660.                                                      int status);
  661.  
  662. /**
  663.  * Test one specific other child processes and invoke the maintenance callback 
  664.  * with the appropriate reason code, if still running, or the appropriate reason 
  665.  * code if the process is no longer healthy.
  666.  * @param ocr The registered other child
  667.  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) if still running
  668.  */
  669. APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr,
  670.                                                int reason);
  671.  
  672. /**
  673.  * Test all registered other child processes and invoke the maintenance callback 
  674.  * with the appropriate reason code, if still running, or the appropriate reason 
  675.  * code if the process is no longer healthy.
  676.  * @param reason The reason code (e.g. APR_OC_REASON_RESTART) to running processes
  677.  */
  678. APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason);
  679.  
  680. /** @deprecated @see apr_proc_other_child_refresh_all
  681.  * @remark Call apr_proc_other_child_refresh_all(APR_OC_REASON_RESTART)
  682.  * or apr_proc_other_child_refresh_all(APR_OC_REASON_RUNNING) instead.
  683.  * @bug The differing implementations of this function on Win32 (_RUNNING checks) 
  684.  * and Unix (used only for _RESTART) are the reason it will be dropped with APR 1.0.
  685.  */
  686. APR_DECLARE(void) apr_proc_other_child_check(void);
  687.  
  688. /** @deprecated @see apr_proc_other_child_alert
  689.  * @bug This function's name had nothing to do with it's purpose
  690.  */
  691. APR_DECLARE(apr_status_t) apr_proc_other_child_read(apr_proc_t *proc, int status);
  692.  
  693.  
  694. /** 
  695.  * Terminate a process.
  696.  * @param proc The process to terminate.
  697.  * @param sig How to kill the process.
  698.  */
  699. APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
  700.  
  701. /**
  702.  * Register a process to be killed when a pool dies.
  703.  * @param a The pool to use to define the processes lifetime 
  704.  * @param proc The process to register
  705.  * @param how How to kill the process, one of:
  706.  * <PRE>
  707.  *         APR_KILL_NEVER         -- process is never sent any signals
  708.  *         APR_KILL_ALWAYS        -- process is sent SIGKILL on apr_pool_t cleanup
  709.  *         APR_KILL_AFTER_TIMEOUT -- SIGTERM, wait 3 seconds, SIGKILL
  710.  *         APR_JUST_WAIT          -- wait forever for the process to complete
  711.  *         APR_KILL_ONLY_ONCE     -- send SIGTERM and then wait
  712.  * </PRE>
  713.  */
  714. APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc,
  715.                                            apr_kill_conditions_e how);
  716.  
  717. #if APR_HAS_THREADS 
  718.  
  719. #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
  720.  
  721. /**
  722.  * Setup the process for a single thread to be used for all signal handling.
  723.  * @warning This must be called before any threads are created
  724.  */
  725. APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
  726.  
  727. /**
  728.  * Make the current thread listen for signals.  This thread will loop
  729.  * forever, calling a provided function whenever it receives a signal.  That
  730.  * functions should return 1 if the signal has been handled, 0 otherwise.
  731.  * @param signal_handler The function to call when a signal is received
  732.  * apr_status_t apr_signal_thread((int)(*signal_handler)(int signum))
  733.  */
  734. APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
  735.  
  736. #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
  737.  
  738. /**
  739.  * Get the child-pool used by the thread from the thread info.
  740.  * @return apr_pool_t the pool
  741.  */
  742. APR_POOL_DECLARE_ACCESSOR(thread);
  743.  
  744. #endif /* APR_HAS_THREADS */
  745.  
  746. /** @} */
  747.  
  748. #ifdef __cplusplus
  749. }
  750. #endif
  751.  
  752. #endif  /* ! APR_THREAD_PROC_H */
  753.  
  754.