rubbos/app/httpd-2.0.64/srclib/apr/include/apr_thread_proc.h

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