1 /* ====================================================================
2 * Copyright (c) 1995-1999 The Apache Group. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
8 * 1. Redistributions of source code must retain the above copyright
9 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in
13 * the documentation and/or other materials provided with the
16 * 3. All advertising materials mentioning features or use of this
17 * software must display the following acknowledgment:
18 * "This product includes software developed by the Apache Group
19 * for use in the Apache HTTP server project (http://www.apache.org/)."
21 * 4. The names "Apache Server" and "Apache Group" must not be used to
22 * endorse or promote products derived from this software without
23 * prior written permission. For written permission, please contact
26 * 5. Products derived from this software may not be called "Apache"
27 * nor may "Apache" appear in their names without prior written
28 * permission of the Apache Group.
30 * 6. Redistributions of any form whatsoever must retain the following
32 * "This product includes software developed by the Apache Group
33 * for use in the Apache HTTP server project (http://www.apache.org/)."
35 * THIS SOFTWARE IS PROVIDED BY THE APACHE GROUP ``AS IS'' AND ANY
36 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
37 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
38 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE GROUP OR
39 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
41 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
42 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
43 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
44 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
45 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
46 * OF THE POSSIBILITY OF SUCH DAMAGE.
47 * ====================================================================
49 * This software consists of voluntary contributions made by many
50 * individuals on behalf of the Apache Group and was originally based
51 * on public domain software written at the National Center for
52 * Supercomputing Applications, University of Illinois, Urbana-Champaign.
53 * For more information on the Apache Group and the Apache HTTP server
54 * project, please see <http://www.apache.org/>.
58 #ifndef APACHE_ALLOC_H
59 #define APACHE_ALLOC_H
66 * Resource allocation routines...
68 * designed so that we don't have to keep track of EVERYTHING so that
69 * it can be explicitly freed later (a fundamentally unsound strategy ---
70 * particularly in the presence of die()).
72 * Instead, we maintain pools, and allocate items (both memory and I/O
73 * handlers) from the pools --- currently there are two, one for per
74 * transaction info, and one for config info. When a transaction is over,
75 * we can delete everything in the per-transaction pool without fear, and
76 * without thinking too hard about it either.
81 /* Arenas for configuration info and transaction info
82 * --- actual layout of the pool structure is private to
86 /* Need declaration of DIR on Win32 */
88 #include "os/win32/readdir.h"
91 typedef struct pool pool
;
92 typedef struct pool ap_pool
;
94 pool
*ap_init_alloc(void); /* Set up everything */
95 API_EXPORT(pool
*) ap_make_sub_pool(pool
*); /* All pools are subpools of permanent_pool */
96 API_EXPORT(void) ap_destroy_pool(pool
*);
98 /* used to guarantee to the pool debugging code that the sub pool will not be
99 * destroyed before the parent pool
105 #define ap_pool_join(a,b)
107 API_EXPORT(void) ap_pool_join(pool
* p
, pool
* sub
);
108 API_EXPORT(pool
*) ap_find_pool(const void *ts
);
109 API_EXPORT(int) ap_pool_is_ancestor(pool
* a
, pool
* b
);
112 /* Clearing out EVERYTHING in an pool... destroys any sub-pools */
114 API_EXPORT(void) ap_clear_pool(struct pool
*);
116 /* Preparing for exec() --- close files, etc., but *don't* flush I/O
117 * buffers, *don't* wait for subprocesses, and *don't* free any memory.
120 API_EXPORT(void) ap_cleanup_for_exec(void);
122 /* routines to allocate memory from an pool... */
124 API_EXPORT(void *) ap_palloc(struct pool
*, int nbytes
);
125 API_EXPORT(void *) ap_pcalloc(struct pool
*, int nbytes
);
126 API_EXPORT(char *) ap_pstrdup(struct pool
*, const char *s
);
127 /* make a nul terminated copy of the n characters starting with s */
128 API_EXPORT(char *) ap_pstrndup(struct pool
*, const char *s
, int n
);
129 API_EXPORT_NONSTD(char *) ap_pstrcat(struct pool
*, ...); /* all '...' must be char* */
130 API_EXPORT_NONSTD(char *) ap_psprintf(struct pool
*, const char *fmt
,
132 __attribute__ ((format(printf
, 2, 3)));
133 API_EXPORT(char *) ap_pvsprintf(struct pool
*, const char *fmt
,
136 /* array and alist management... keeping lists of things.
137 * Common enough to want common support code ...
148 API_EXPORT(array_header
*) ap_make_array(pool
* p
, int nelts
,
150 API_EXPORT(void *) ap_push_array(array_header
*);
151 API_EXPORT(void) ap_array_cat(array_header
* dst
,
152 const array_header
* src
);
153 API_EXPORT(array_header
*) ap_append_arrays(pool
*,
154 const array_header
*,
155 const array_header
*);
157 /* ap_array_pstrcat generates a new string from the pool containing
158 * the concatenated sequence of substrings referenced as elements within
159 * the array. The string will be empty if all substrings are empty or null,
160 * or if there are no elements in the array.
161 * If sep is non-NUL, it will be inserted between elements as a separator.
163 API_EXPORT(char *) ap_array_pstrcat(pool
* p
, const array_header
* arr
,
166 /* copy_array copies the *entire* array. copy_array_hdr just copies
167 * the header, and arranges for the elements to be copied if (and only
168 * if) the code subsequently does a push or arraycat.
171 API_EXPORT(array_header
*) ap_copy_array(pool
* p
,
172 const array_header
* src
);
173 API_EXPORT(array_header
*) ap_copy_array_hdr(pool
* p
,
174 const array_header
* src
);
177 /* Tables. Implemented alist style, for now, though we try to keep
178 * it so that imposing a hash table structure on top in the future
179 * wouldn't be *too* hard...
181 * Note that key comparisons for these are case-insensitive, largely
182 * because that's what's appropriate and convenient everywhere they're
183 * currently being used...
186 typedef struct table table
;
189 char *key
; /* maybe NULL in future;
190 * check when iterating thru table_elts
195 API_EXPORT(table
*) ap_make_table(pool
* p
, int nelts
);
196 API_EXPORT(table
*) ap_copy_table(pool
* p
, const table
*);
197 API_EXPORT(void) ap_clear_table(table
*);
198 API_EXPORT(const char *) ap_table_get(const table
*, const char *);
199 API_EXPORT(void) ap_table_set(table
*, const char *name
,
201 API_EXPORT(void) ap_table_setn(table
*, const char *name
,
203 API_EXPORT(void) ap_table_merge(table
*, const char *name
,
204 const char *more_val
);
205 API_EXPORT(void) ap_table_mergen(table
*, const char *name
,
206 const char *more_val
);
207 API_EXPORT(void) ap_table_unset(table
*, const char *key
);
208 API_EXPORT(void) ap_table_add(table
*, const char *name
,
210 API_EXPORT(void) ap_table_addn(table
*, const char *name
,
213 ap_table_do(int (*comp
) (void *, const char *, const char *), void *rec
,
214 const table
* t
, ...);
216 API_EXPORT(table
*) ap_overlay_tables(pool
* p
, const table
* overlay
,
219 /* Conceptually, ap_overlap_tables does this:
221 array_header *barr = ap_table_elts(b);
222 table_entry *belt = (table_entry *)barr->elts;
225 for (i = 0; i < barr->nelts; ++i) {
226 if (flags & AP_OVERLAP_TABLES_MERGE) {
227 ap_table_mergen(a, belt[i].key, belt[i].val);
230 ap_table_setn(a, belt[i].key, belt[i].val);
234 Except that it is more efficient (less space and cpu-time) especially
235 when b has many elements.
237 Notice the assumptions on the keys and values in b -- they must be
238 in an ancestor of a's pool. In practice b and a are usually from
241 #define AP_OVERLAP_TABLES_SET (0)
242 #define AP_OVERLAP_TABLES_MERGE (1)
243 API_EXPORT(void) ap_overlap_tables(table
* a
, const table
* b
,
246 /* XXX: these know about the definition of struct table in alloc.c. That
247 * definition is not here because it is supposed to be private, and by not
248 * placing it here we are able to get compile-time diagnostics from modules
249 * written which assume that a table is the same as an array_header. -djg
251 #define ap_table_elts(t) ((array_header *)(t))
252 #define ap_is_empty_table(t) (((t) == NULL)||(((array_header *)(t))->nelts == 0))
254 /* routines to remember allocation of other sorts of things...
255 * generic interface first. Note that we want to have two separate
256 * cleanup functions in the general case, one for exec() preparation,
257 * to keep CGI scripts and the like from inheriting access to things
258 * they shouldn't be able to touch, and one for actually cleaning up,
259 * when the actual server process wants to get rid of the thing,
262 * kill_cleanup disarms a cleanup, presumably because the resource in
263 * question has been closed, freed, or whatever, and it's scarce
264 * enough to want to reclaim (e.g., descriptors). It arranges for the
265 * resource not to be cleaned up a second time (it might have been
266 * reallocated). run_cleanup does the same, but runs it first.
268 * Cleanups are identified for purposes of finding & running them off by the
269 * plain_cleanup and data, which should presumably be unique.
271 * NB any code which invokes register_cleanup or kill_cleanup directly
272 * is a critical section which should be guarded by block_alarms() and
273 * unblock_alarms() below...
276 API_EXPORT(void) ap_register_cleanup(pool
* p
, void *data
,
277 void (*plain_cleanup
) (void *),
278 void (*child_cleanup
) (void *));
280 API_EXPORT(void) ap_kill_cleanup(pool
* p
, void *data
,
281 void (*plain_cleanup
) (void *));
282 API_EXPORT(void) ap_run_cleanup(pool
* p
, void *data
,
283 void (*cleanup
) (void *));
285 /* A "do-nothing" cleanup, for register_cleanup; it's faster to do
286 * things this way than to test for NULL. */
287 API_EXPORT_NONSTD(void) ap_null_cleanup(void *data
);
289 /* The time between when a resource is actually allocated, and when it
290 * its cleanup is registered is a critical section, during which the
291 * resource could leak if we got interrupted or timed out. So, anything
292 * which registers cleanups should bracket resource allocation and the
293 * cleanup registry with these. (This is done internally by run_cleanup).
295 * NB they are actually implemented in http_main.c, since they are bound
296 * up with timeout handling in general...
300 #define ap_block_alarms() (0)
301 #define ap_unblock_alarms() (0)
303 API_EXPORT(void) ap_block_alarms(void);
304 API_EXPORT(void) ap_unblock_alarms(void);
307 /* Common cases which want utility support..
308 * the note_cleanups_for_foo routines are for
311 API_EXPORT(FILE *) ap_pfopen(struct pool
*, const char *name
,
313 API_EXPORT(FILE *) ap_pfdopen(struct pool
*, int fd
, const char *fmode
);
314 API_EXPORT(int) ap_popenf(struct pool
*, const char *name
, int flg
,
317 API_EXPORT(void) ap_note_cleanups_for_file(pool
*, FILE *);
318 API_EXPORT(void) ap_note_cleanups_for_fd(pool
*, int);
320 API_EXPORT(void) ap_note_cleanups_for_h(pool
*, HANDLE
);
322 API_EXPORT(void) ap_kill_cleanups_for_fd(pool
* p
, int fd
);
324 API_EXPORT(void) ap_note_cleanups_for_socket(pool
*, int);
325 API_EXPORT(void) ap_kill_cleanups_for_socket(pool
* p
, int sock
);
326 API_EXPORT(int) ap_psocket(pool
* p
, int, int, int);
327 API_EXPORT(int) ap_pclosesocket(pool
* a
, int sock
);
329 API_EXPORT(regex_t
*) ap_pregcomp(pool
* p
, const char *pattern
,
331 API_EXPORT(void) ap_pregfree(pool
* p
, regex_t
* reg
);
333 /* routines to note closes... file descriptors are constrained enough
334 * on some systems that we want to support this.
337 API_EXPORT(int) ap_pfclose(struct pool
*, FILE *);
338 API_EXPORT(int) ap_pclosef(struct pool
*, int fd
);
340 API_EXPORT(int) ap_pcloseh(struct pool
*, HANDLE hDevice
);
343 /* routines to deal with directories */
344 API_EXPORT(DIR *) ap_popendir(pool
* p
, const char *name
);
345 API_EXPORT(void) ap_pclosedir(pool
* p
, DIR * d
);
347 /* ... even child processes (which we may want to wait for,
348 * or to kill outright, on unexpected termination).
350 * ap_spawn_child is a utility routine which handles an awful lot of
351 * the rigamarole associated with spawning a child --- it arranges
352 * for pipes to the child's stdin and stdout, if desired (if not,
353 * set the associated args to NULL). It takes as args a function
354 * to call in the child, and an argument to be passed to the function.
357 enum kill_conditions
{
358 kill_never
, /* process is never sent any signals */
359 kill_always
, /* process is sent SIGKILL on pool cleanup */
360 kill_after_timeout
, /* SIGTERM, wait 3 seconds, SIGKILL */
361 just_wait
, /* wait forever for the process to complete */
362 kill_only_once
/* send SIGTERM and then wait */
365 typedef struct child_info child_info
;
366 API_EXPORT(void) ap_note_subprocess(pool
* a
, pid_t pid
,
367 enum kill_conditions how
);
368 API_EXPORT(int) ap_spawn_child(pool
*, int (*)(void *, child_info
*),
369 void *, enum kill_conditions
,
370 FILE ** pipe_in
, FILE ** pipe_out
,
373 /* magic numbers --- min free bytes to consider a free pool block useable,
374 * and the min amount to allocate if we have to go to malloc() */
376 #ifndef BLOCK_MINFREE
377 #define BLOCK_MINFREE 4096
379 #ifndef BLOCK_MINALLOC
380 #define BLOCK_MINALLOC 8192
383 /* Finally, some accounting */
385 API_EXPORT(long) ap_bytes_in_pool(pool
* p
);
386 API_EXPORT(long) ap_bytes_in_free_blocks(void);
391 #endif /* !APACHE_ALLOC_H */