Apache Portable Runtime
Main Page
Related Pages
Modules
Namespaces
Data Structures
Files
File List
Globals
All
Data Structures
Namespaces
Files
Functions
Variables
Typedefs
Enumerations
Enumerator
Macros
Groups
Pages
usr
include
apr-1
apr_thread_proc.h
Go to the documentation of this file.
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 the pool 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
* Return the pool 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
Generated by
1.8.3.1