Apache Portable Runtime: apr_thread

00001 /* Licensed to the Apache Software Foundation (ASF) under one or more
00002  * contributor license agreements.  See the NOTICE file distributed with
00003  * this work for additional information regarding copyright ownership.
00004  * The ASF licenses this file to You under the Apache License, Version 2.0
00005  * (the "License"); you may not use this file except in compliance with
00006  * the License.  You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef APR_THREAD_PROC_H
00018 #define APR_THREAD_PROC_H
00019 
00025 #include "apr.h"
00026 #include "apr_file_io.h"
00027 #include "apr_pools.h"
00028 #include "apr_errno.h"
00029 
00030 #if APR_HAVE_STRUCT_RLIMIT
00031 #include <sys/time.h>
00032 #include <sys/resource.h>
00033 #endif
00034 
00035 #ifdef __cplusplus
00036 extern "C" {
00037 #endif /* __cplusplus */
00038 
00045 typedef enum {
00046     APR_SHELLCMD,       
00047     APR_PROGRAM,        
00048     APR_PROGRAM_ENV,    
00049     APR_PROGRAM_PATH,   
00050     APR_SHELLCMD_ENV    
00053 } apr_cmdtype_e;
00054 
00055 typedef enum {
00056     APR_WAIT,           
00057     APR_NOWAIT          
00058 } apr_wait_how_e;
00059 
00060 /* I am specifically calling out the values so that the macros below make
00061  * more sense.  Yes, I know I don't need to, but I am hoping this makes what
00062  * I am doing more clear.  If you want to add more reasons to exit, continue
00063  * to use bitmasks.
00064  */
00065 typedef enum {
00066     APR_PROC_EXIT = 1,          
00067     APR_PROC_SIGNAL = 2,        
00068     APR_PROC_SIGNAL_CORE = 4    
00069 } apr_exit_why_e;
00070 
00072 #define APR_PROC_CHECK_EXIT(x)        (x & APR_PROC_EXIT)
00073 
00074 #define APR_PROC_CHECK_SIGNALED(x)    (x & APR_PROC_SIGNAL)
00075 
00076 #define APR_PROC_CHECK_CORE_DUMP(x)   (x & APR_PROC_SIGNAL_CORE)
00077 
00079 #define APR_NO_PIPE          0
00080 
00082 #define APR_FULL_BLOCK       1
00083 
00084 #define APR_FULL_NONBLOCK    2
00085 
00086 #define APR_PARENT_BLOCK     3
00087 
00088 #define APR_CHILD_BLOCK      4
00089 
00091 #define APR_LIMIT_CPU        0
00092 
00093 #define APR_LIMIT_MEM        1
00094 
00095 #define APR_LIMIT_NPROC      2
00096 
00097 #define APR_LIMIT_NOFILE     3
00098 
00103 #define APR_OC_REASON_DEATH         0     
00105 #define APR_OC_REASON_UNWRITABLE    1     
00106 #define APR_OC_REASON_RESTART       2     
00110 #define APR_OC_REASON_UNREGISTER    3     
00113 #define APR_OC_REASON_LOST          4     
00115 #define APR_OC_REASON_RUNNING       5     
00122 typedef struct apr_proc_t {
00123 
00124     pid_t pid;
00126     apr_file_t *in;
00128     apr_file_t *out;
00130     apr_file_t *err;
00131 #if APR_HAS_PROC_INVOKED || defined(DOXYGEN)
00132 
00139     char *invoked;
00140 #endif
00141 #if defined(WIN32) || defined(DOXYGEN)
00142 
00148     HANDLE hproc;
00149 #endif
00150 } apr_proc_t;
00151 
00162 typedef void (apr_child_errfn_t)(apr_pool_t *proc, apr_status_t err,
00163                                  const char *description);
00164 
00166 typedef struct apr_thread_t           apr_thread_t;
00167 
00169 typedef struct apr_threadattr_t       apr_threadattr_t;
00170 
00172 typedef struct apr_procattr_t         apr_procattr_t;
00173 
00175 typedef struct apr_thread_once_t      apr_thread_once_t;
00176 
00178 typedef struct apr_threadkey_t        apr_threadkey_t;
00179 
00181 typedef struct apr_other_child_rec_t  apr_other_child_rec_t;
00182 
00186 typedef void *(APR_THREAD_FUNC *apr_thread_start_t)(apr_thread_t*, void*);
00187 
00188 typedef enum {
00189     APR_KILL_NEVER,             
00190     APR_KILL_ALWAYS,            
00191     APR_KILL_AFTER_TIMEOUT,     
00192     APR_JUST_WAIT,              
00193     APR_KILL_ONLY_ONCE          
00194 } apr_kill_conditions_e;
00195 
00196 /* Thread Function definitions */
00197 
00198 #if APR_HAS_THREADS
00199 
00205 APR_DECLARE(apr_status_t) apr_threadattr_create(apr_threadattr_t **new_attr, 
00206                                                 apr_pool_t *cont);
00207 
00213 APR_DECLARE(apr_status_t) apr_threadattr_detach_set(apr_threadattr_t *attr, 
00214                                                    apr_int32_t on);
00215 
00220 APR_DECLARE(apr_status_t) apr_threadattr_detach_get(apr_threadattr_t *attr);
00221 
00227 APR_DECLARE(apr_status_t) apr_threadattr_stacksize_set(apr_threadattr_t *attr,
00228                                                        apr_size_t stacksize);
00229 
00238 APR_DECLARE(apr_status_t) apr_thread_create(apr_thread_t **new_thread, 
00239                                             apr_threadattr_t *attr, 
00240                                             apr_thread_start_t func, 
00241                                             void *data, apr_pool_t *cont);
00242 
00248 APR_DECLARE(apr_status_t) apr_thread_exit(apr_thread_t *thd, 
00249                                           apr_status_t retval);
00250 
00256 APR_DECLARE(apr_status_t) apr_thread_join(apr_status_t *retval, 
00257                                           apr_thread_t *thd); 
00258 
00262 APR_DECLARE(void) apr_thread_yield(void);
00263 
00270 APR_DECLARE(apr_status_t) apr_thread_once_init(apr_thread_once_t **control,
00271                                                apr_pool_t *p);
00272 
00282 APR_DECLARE(apr_status_t) apr_thread_once(apr_thread_once_t *control,
00283                                           void (*func)(void));
00284 
00289 APR_DECLARE(apr_status_t) apr_thread_detach(apr_thread_t *thd);
00290 
00297 APR_DECLARE(apr_status_t) apr_thread_data_get(void **data, const char *key,
00298                                              apr_thread_t *thread);
00299 
00307 APR_DECLARE(apr_status_t) apr_thread_data_set(void *data, const char *key,
00308                                              apr_status_t (*cleanup) (void *),
00309                                              apr_thread_t *thread);
00310 
00317 APR_DECLARE(apr_status_t) apr_threadkey_private_create(apr_threadkey_t **key, 
00318                                                     void (*dest)(void *),
00319                                                     apr_pool_t *cont);
00320 
00326 APR_DECLARE(apr_status_t) apr_threadkey_private_get(void **new_mem, 
00327                                                  apr_threadkey_t *key);
00328 
00334 APR_DECLARE(apr_status_t) apr_threadkey_private_set(void *priv, 
00335                                                  apr_threadkey_t *key);
00336 
00341 APR_DECLARE(apr_status_t) apr_threadkey_private_delete(apr_threadkey_t *key);
00342 
00349 APR_DECLARE(apr_status_t) apr_threadkey_data_get(void **data, const char *key,
00350                                                 apr_threadkey_t *threadkey);
00351 
00359 APR_DECLARE(apr_status_t) apr_threadkey_data_set(void *data, const char *key,
00360                                                 apr_status_t (*cleanup) (void *),
00361                                                 apr_threadkey_t *threadkey);
00362 
00363 #endif
00364 
00370 APR_DECLARE(apr_status_t) apr_procattr_create(apr_procattr_t **new_attr,
00371                                                   apr_pool_t *cont);
00372 
00381 APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, 
00382                                              apr_int32_t in, apr_int32_t out,
00383                                              apr_int32_t err);
00384 
00397 APR_DECLARE(apr_status_t) apr_procattr_child_in_set(struct apr_procattr_t *attr,
00398                                                   apr_file_t *child_in,
00399                                                   apr_file_t *parent_in);
00400 
00411 APR_DECLARE(apr_status_t) apr_procattr_child_out_set(struct apr_procattr_t *attr,
00412                                                    apr_file_t *child_out,
00413                                                    apr_file_t *parent_out);
00414 
00425 APR_DECLARE(apr_status_t) apr_procattr_child_err_set(struct apr_procattr_t *attr,
00426                                                    apr_file_t *child_err,
00427                                                    apr_file_t *parent_err);
00428 
00436 APR_DECLARE(apr_status_t) apr_procattr_dir_set(apr_procattr_t *attr, 
00437                                               const char *dir);
00438 
00450 APR_DECLARE(apr_status_t) apr_procattr_cmdtype_set(apr_procattr_t *attr,
00451                                                   apr_cmdtype_e cmd);
00452 
00458 APR_DECLARE(apr_status_t) apr_procattr_detach_set(apr_procattr_t *attr, 
00459                                                  apr_int32_t detach);
00460 
00461 #if APR_HAVE_STRUCT_RLIMIT
00462 
00474 APR_DECLARE(apr_status_t) apr_procattr_limit_set(apr_procattr_t *attr, 
00475                                                 apr_int32_t what,
00476                                                 struct rlimit *limit);
00477 #endif
00478 
00490 APR_DECLARE(apr_status_t) apr_procattr_child_errfn_set(apr_procattr_t *attr,
00491                                                        apr_child_errfn_t *errfn);
00492 
00505 APR_DECLARE(apr_status_t) apr_procattr_error_check_set(apr_procattr_t *attr,
00506                                                        apr_int32_t chk);
00507 
00515 APR_DECLARE(apr_status_t) apr_procattr_addrspace_set(apr_procattr_t *attr,
00516                                                        apr_int32_t addrspace);
00517 
00518 #if APR_HAS_FORK
00519 
00525 APR_DECLARE(apr_status_t) apr_proc_fork(apr_proc_t *proc, apr_pool_t *cont);
00526 #endif
00527 
00542 APR_DECLARE(apr_status_t) apr_proc_create(apr_proc_t *new_proc,
00543                                              const char *progname,
00544                                              const char * const *args,
00545                                              const char * const *env, 
00546                                              apr_procattr_t *attr, 
00547                                              apr_pool_t *cont);
00548 
00575 APR_DECLARE(apr_status_t) apr_proc_wait(apr_proc_t *proc,
00576                                         int *exitcode, apr_exit_why_e *exitwhy,
00577                                         apr_wait_how_e waithow);
00578 
00605 APR_DECLARE(apr_status_t) apr_proc_wait_all_procs(apr_proc_t *proc,
00606                                                   int *exitcode,
00607                                                   apr_exit_why_e *exitwhy,
00608                                                   apr_wait_how_e waithow,
00609                                                   apr_pool_t *p);
00610 
00611 #define APR_PROC_DETACH_FOREGROUND 0    
00612 #define APR_PROC_DETACH_DAEMONIZE 1     
00620 APR_DECLARE(apr_status_t) apr_proc_detach(int daemonize);
00621 
00639 APR_DECLARE(void) apr_proc_other_child_register(apr_proc_t *proc, 
00640                                            void (*maintenance) (int reason, 
00641                                                                 void *, 
00642                                                                 int status),
00643                                            void *data, apr_file_t *write_fd,
00644                                            apr_pool_t *p);
00645 
00655 APR_DECLARE(void) apr_proc_other_child_unregister(void *data);
00656 
00677 APR_DECLARE(apr_status_t) apr_proc_other_child_alert(apr_proc_t *proc, 
00678                                                      int reason,
00679                                                      int status);
00680 
00688 APR_DECLARE(void) apr_proc_other_child_refresh(apr_other_child_rec_t *ocr,
00689                                                int reason);
00690 
00697 APR_DECLARE(void) apr_proc_other_child_refresh_all(int reason);
00698 
00705 APR_DECLARE(void) apr_proc_other_child_check(void);
00706 
00710 APR_DECLARE(apr_status_t) apr_proc_other_child_read(apr_proc_t *proc, int status);
00711 
00712 
00718 APR_DECLARE(apr_status_t) apr_proc_kill(apr_proc_t *proc, int sig);
00719 
00733 APR_DECLARE(void) apr_pool_note_subprocess(apr_pool_t *a, apr_proc_t *proc,
00734                                            apr_kill_conditions_e how);
00735 
00736 #if APR_HAS_THREADS 
00737 
00738 #if (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2)
00739 
00744 APR_DECLARE(apr_status_t) apr_setup_signal_thread(void);
00745 
00753 APR_DECLARE(apr_status_t) apr_signal_thread(int(*signal_handler)(int signum));
00754 
00755 #endif /* (APR_HAVE_SIGWAIT || APR_HAVE_SIGSUSPEND) && !defined(OS2) */
00756 
00761 APR_POOL_DECLARE_ACCESSOR(thread);
00762 
00763 #endif /* APR_HAS_THREADS */
00764 
00767 #ifdef __cplusplus
00768 }
00769 #endif
00770 
00771 #endif  /* ! APR_THREAD_PROC_H */
00772
apr_thread_proc.h
