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