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