Annotation of win32/apache13/src/include/ap_alloc.h, revision 1.1
1.1 ! parser 1: /* ====================================================================
! 2: * Copyright (c) 1995-1999 The Apache Group. All rights reserved.
! 3: *
! 4: * Redistribution and use in source and binary forms, with or without
! 5: * modification, are permitted provided that the following conditions
! 6: * are met:
! 7: *
! 8: * 1. Redistributions of source code must retain the above copyright
! 9: * notice, this list of conditions and the following disclaimer.
! 10: *
! 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
! 14: * distribution.
! 15: *
! 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/)."
! 20: *
! 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
! 24: * apache@apache.org.
! 25: *
! 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.
! 29: *
! 30: * 6. Redistributions of any form whatsoever must retain the following
! 31: * acknowledgment:
! 32: * "This product includes software developed by the Apache Group
! 33: * for use in the Apache HTTP server project (http://www.apache.org/)."
! 34: *
! 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: * ====================================================================
! 48: *
! 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/>.
! 55: *
! 56: */
! 57:
! 58: #ifndef APACHE_ALLOC_H
! 59: #define APACHE_ALLOC_H
! 60:
! 61: #ifdef __cplusplus
! 62: extern "C" {
! 63: #endif
! 64:
! 65: /*
! 66: * Resource allocation routines...
! 67: *
! 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()).
! 71: *
! 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.
! 77: *
! 78: * rst
! 79: */
! 80:
! 81: /* Arenas for configuration info and transaction info
! 82: * --- actual layout of the pool structure is private to
! 83: * alloc.c.
! 84: */
! 85:
! 86: /* Need declaration of DIR on Win32 */
! 87: #ifdef WIN32
! 88: #include "../os/win32/readdir.h"
! 89: #endif
! 90:
! 91: typedef struct pool pool;
! 92: typedef struct pool ap_pool;
! 93:
! 94: pool * ap_init_alloc(void); /* Set up everything */
! 95: void ap_cleanup_alloc(void);
! 96: API_EXPORT(pool *) ap_make_sub_pool(pool *); /* All pools are subpools of permanent_pool */
! 97: API_EXPORT(void) ap_destroy_pool(pool *);
! 98:
! 99: /* pools have nested lifetimes -- sub_pools are destroyed when the
! 100: * parent pool is cleared. We allow certain liberties with operations
! 101: * on things such as tables (and on other structures in a more general
! 102: * sense) where we allow the caller to insert values into a table which
! 103: * were not allocated from the table's pool. The table's data will
! 104: * remain valid as long as all the pools from which its values are
! 105: * allocated remain valid.
! 106: *
! 107: * For example, if B is a sub pool of A, and you build a table T in
! 108: * pool B, then it's safe to insert data allocated in A or B into T
! 109: * (because B lives at most as long as A does, and T is destroyed when
! 110: * B is cleared/destroyed). On the other hand, if S is a table in
! 111: * pool A, it is safe to insert data allocated in A into S, but it
! 112: * is *not safe* to insert data allocated from B into S... because
! 113: * B can be cleared/destroyed before A is (which would leave dangling
! 114: * pointers in T's data structures).
! 115: *
! 116: * In general we say that it is safe to insert data into a table T
! 117: * if the data is allocated in any ancestor of T's pool. This is the
! 118: * basis on which the POOL_DEBUG code works -- it tests these ancestor
! 119: * relationships for all data inserted into tables. POOL_DEBUG also
! 120: * provides tools (ap_find_pool, and ap_pool_is_ancestor) for other
! 121: * folks to implement similar restrictions for their own data
! 122: * structures.
! 123: *
! 124: * However, sometimes this ancestor requirement is inconvenient --
! 125: * sometimes we're forced to create a sub pool (such as through
! 126: * ap_sub_req_lookup_uri), and the sub pool is guaranteed to have
! 127: * the same lifetime as the parent pool. This is a guarantee implemented
! 128: * by the *caller*, not by the pool code. That is, the caller guarantees
! 129: * they won't destroy the sub pool individually prior to destroying the
! 130: * parent pool.
! 131: *
! 132: * In this case the caller must call ap_pool_join() to indicate this
! 133: * guarantee to the POOL_DEBUG code. There are a few examples spread
! 134: * through the standard modules.
! 135: */
! 136: #ifndef POOL_DEBUG
! 137: #ifdef ap_pool_join
! 138: #undef ap_pool_join
! 139: #endif
! 140: #define ap_pool_join(a,b)
! 141: #else
! 142: API_EXPORT(void) ap_pool_join(pool *p, pool *sub);
! 143: API_EXPORT(pool *) ap_find_pool(const void *ts);
! 144: API_EXPORT(int) ap_pool_is_ancestor(pool *a, pool *b);
! 145: #endif
! 146:
! 147: /* Clearing out EVERYTHING in an pool... destroys any sub-pools */
! 148:
! 149: API_EXPORT(void) ap_clear_pool(struct pool *);
! 150:
! 151: /* Preparing for exec() --- close files, etc., but *don't* flush I/O
! 152: * buffers, *don't* wait for subprocesses, and *don't* free any memory.
! 153: */
! 154:
! 155: API_EXPORT(void) ap_cleanup_for_exec(void);
! 156:
! 157: /* routines to allocate memory from an pool... */
! 158:
! 159: API_EXPORT(void *) ap_palloc(struct pool *, int nbytes);
! 160: API_EXPORT(void *) ap_pcalloc(struct pool *, int nbytes);
! 161: API_EXPORT(char *) ap_pstrdup(struct pool *, const char *s);
! 162: /* make a nul terminated copy of the n characters starting with s */
! 163: API_EXPORT(char *) ap_pstrndup(struct pool *, const char *s, int n);
! 164: API_EXPORT_NONSTD(char *) ap_pstrcat(struct pool *,...); /* all '...' must be char* */
! 165: API_EXPORT_NONSTD(char *) ap_psprintf(struct pool *, const char *fmt, ...)
! 166: __attribute__((format(printf,2,3)));
! 167: API_EXPORT(char *) ap_pvsprintf(struct pool *, const char *fmt, va_list);
! 168:
! 169: /* array and alist management... keeping lists of things.
! 170: * Common enough to want common support code ...
! 171: */
! 172:
! 173: typedef struct {
! 174: ap_pool *pool;
! 175: int elt_size;
! 176: int nelts;
! 177: int nalloc;
! 178: char *elts;
! 179: } array_header;
! 180:
! 181: API_EXPORT(array_header *) ap_make_array(pool *p, int nelts, int elt_size);
! 182: API_EXPORT(void *) ap_push_array(array_header *);
! 183: API_EXPORT(void) ap_array_cat(array_header *dst, const array_header *src);
! 184: API_EXPORT(array_header *) ap_append_arrays(pool *, const array_header *,
! 185: const array_header *);
! 186:
! 187: /* ap_array_pstrcat generates a new string from the pool containing
! 188: * the concatenated sequence of substrings referenced as elements within
! 189: * the array. The string will be empty if all substrings are empty or null,
! 190: * or if there are no elements in the array.
! 191: * If sep is non-NUL, it will be inserted between elements as a separator.
! 192: */
! 193: API_EXPORT(char *) ap_array_pstrcat(pool *p, const array_header *arr,
! 194: const char sep);
! 195:
! 196: /* copy_array copies the *entire* array. copy_array_hdr just copies
! 197: * the header, and arranges for the elements to be copied if (and only
! 198: * if) the code subsequently does a push or arraycat.
! 199: */
! 200:
! 201: API_EXPORT(array_header *) ap_copy_array(pool *p, const array_header *src);
! 202: API_EXPORT(array_header *) ap_copy_array_hdr(pool *p, const array_header *src);
! 203:
! 204:
! 205: /* Tables. Implemented alist style, for now, though we try to keep
! 206: * it so that imposing a hash table structure on top in the future
! 207: * wouldn't be *too* hard...
! 208: *
! 209: * Note that key comparisons for these are case-insensitive, largely
! 210: * because that's what's appropriate and convenient everywhere they're
! 211: * currently being used...
! 212: */
! 213:
! 214: typedef struct table table;
! 215:
! 216: typedef struct {
! 217: char *key; /* maybe NULL in future;
! 218: * check when iterating thru table_elts
! 219: */
! 220: char *val;
! 221: } table_entry;
! 222:
! 223: API_EXPORT(table *) ap_make_table(pool *p, int nelts);
! 224: API_EXPORT(table *) ap_copy_table(pool *p, const table *);
! 225: API_EXPORT(void) ap_clear_table(table *);
! 226: API_EXPORT(const char *) ap_table_get(const table *, const char *);
! 227: API_EXPORT(void) ap_table_set(table *, const char *name, const char *val);
! 228: API_EXPORT(void) ap_table_setn(table *, const char *name, const char *val);
! 229: API_EXPORT(void) ap_table_merge(table *, const char *name, const char *more_val);
! 230: API_EXPORT(void) ap_table_mergen(table *, const char *name, const char *more_val);
! 231: API_EXPORT(void) ap_table_unset(table *, const char *key);
! 232: API_EXPORT(void) ap_table_add(table *, const char *name, const char *val);
! 233: API_EXPORT(void) ap_table_addn(table *, const char *name, const char *val);
! 234: API_EXPORT(void) ap_table_do(int (*comp) (void *, const char *, const char *), void *rec,
! 235: const table *t,...);
! 236:
! 237: API_EXPORT(table *) ap_overlay_tables(pool *p, const table *overlay, const table *base);
! 238:
! 239: /* Conceptually, ap_overlap_tables does this:
! 240:
! 241: array_header *barr = ap_table_elts(b);
! 242: table_entry *belt = (table_entry *)barr->elts;
! 243: int i;
! 244:
! 245: for (i = 0; i < barr->nelts; ++i) {
! 246: if (flags & AP_OVERLAP_TABLES_MERGE) {
! 247: ap_table_mergen(a, belt[i].key, belt[i].val);
! 248: }
! 249: else {
! 250: ap_table_setn(a, belt[i].key, belt[i].val);
! 251: }
! 252: }
! 253:
! 254: Except that it is more efficient (less space and cpu-time) especially
! 255: when b has many elements.
! 256:
! 257: Notice the assumptions on the keys and values in b -- they must be
! 258: in an ancestor of a's pool. In practice b and a are usually from
! 259: the same pool.
! 260: */
! 261: #define AP_OVERLAP_TABLES_SET (0)
! 262: #define AP_OVERLAP_TABLES_MERGE (1)
! 263: API_EXPORT(void) ap_overlap_tables(table *a, const table *b, unsigned flags);
! 264:
! 265: /* XXX: these know about the definition of struct table in alloc.c. That
! 266: * definition is not here because it is supposed to be private, and by not
! 267: * placing it here we are able to get compile-time diagnostics from modules
! 268: * written which assume that a table is the same as an array_header. -djg
! 269: */
! 270: #define ap_table_elts(t) ((array_header *)(t))
! 271: #define ap_is_empty_table(t) (((t) == NULL)||(((array_header *)(t))->nelts == 0))
! 272:
! 273: /* routines to remember allocation of other sorts of things...
! 274: * generic interface first. Note that we want to have two separate
! 275: * cleanup functions in the general case, one for exec() preparation,
! 276: * to keep CGI scripts and the like from inheriting access to things
! 277: * they shouldn't be able to touch, and one for actually cleaning up,
! 278: * when the actual server process wants to get rid of the thing,
! 279: * whatever it is.
! 280: *
! 281: * kill_cleanup disarms a cleanup, presumably because the resource in
! 282: * question has been closed, freed, or whatever, and it's scarce
! 283: * enough to want to reclaim (e.g., descriptors). It arranges for the
! 284: * resource not to be cleaned up a second time (it might have been
! 285: * reallocated). run_cleanup does the same, but runs it first.
! 286: *
! 287: * Cleanups are identified for purposes of finding & running them off by the
! 288: * plain_cleanup and data, which should presumably be unique.
! 289: *
! 290: * NB any code which invokes register_cleanup or kill_cleanup directly
! 291: * is a critical section which should be guarded by block_alarms() and
! 292: * unblock_alarms() below...
! 293: */
! 294:
! 295: API_EXPORT(void) ap_register_cleanup(pool *p, void *data,
! 296: void (*plain_cleanup) (void *),
! 297: void (*child_cleanup) (void *));
! 298:
! 299: API_EXPORT(void) ap_kill_cleanup(pool *p, void *data, void (*plain_cleanup) (void *));
! 300: API_EXPORT(void) ap_run_cleanup(pool *p, void *data, void (*cleanup) (void *));
! 301:
! 302: /* A "do-nothing" cleanup, for register_cleanup; it's faster to do
! 303: * things this way than to test for NULL. */
! 304: API_EXPORT_NONSTD(void) ap_null_cleanup(void *data);
! 305:
! 306: /* The time between when a resource is actually allocated, and when it
! 307: * its cleanup is registered is a critical section, during which the
! 308: * resource could leak if we got interrupted or timed out. So, anything
! 309: * which registers cleanups should bracket resource allocation and the
! 310: * cleanup registry with these. (This is done internally by run_cleanup).
! 311: *
! 312: * NB they are actually implemented in http_main.c, since they are bound
! 313: * up with timeout handling in general...
! 314: */
! 315:
! 316: #ifdef TPF
! 317: #define ap_block_alarms() (0)
! 318: #define ap_unblock_alarms() (0)
! 319: #else
! 320: API_EXPORT(void) ap_block_alarms(void);
! 321: API_EXPORT(void) ap_unblock_alarms(void);
! 322: #endif /* TPF */
! 323:
! 324: /* Common cases which want utility support..
! 325: * the note_cleanups_for_foo routines are for
! 326: */
! 327:
! 328: API_EXPORT(FILE *) ap_pfopen(struct pool *, const char *name, const char *fmode);
! 329: API_EXPORT(FILE *) ap_pfdopen(struct pool *, int fd, const char *fmode);
! 330: API_EXPORT(int) ap_popenf(struct pool *, const char *name, int flg, int mode);
! 331:
! 332: API_EXPORT(void) ap_note_cleanups_for_file(pool *, FILE *);
! 333: API_EXPORT(void) ap_note_cleanups_for_fd(pool *, int);
! 334: #ifdef WIN32
! 335: API_EXPORT(void) ap_note_cleanups_for_h(pool *, HANDLE);
! 336: #endif
! 337: API_EXPORT(void) ap_kill_cleanups_for_fd(pool *p, int fd);
! 338:
! 339: API_EXPORT(void) ap_note_cleanups_for_socket(pool *, int);
! 340: API_EXPORT(void) ap_kill_cleanups_for_socket(pool *p, int sock);
! 341: API_EXPORT(int) ap_psocket(pool *p, int, int, int);
! 342: API_EXPORT(int) ap_pclosesocket(pool *a, int sock);
! 343:
! 344: API_EXPORT(regex_t *) ap_pregcomp(pool *p, const char *pattern, int cflags);
! 345: API_EXPORT(void) ap_pregfree(pool *p, regex_t * reg);
! 346:
! 347: /* routines to note closes... file descriptors are constrained enough
! 348: * on some systems that we want to support this.
! 349: */
! 350:
! 351: API_EXPORT(int) ap_pfclose(struct pool *, FILE *);
! 352: API_EXPORT(int) ap_pclosef(struct pool *, int fd);
! 353: #ifdef WIN32
! 354: API_EXPORT(int) ap_pcloseh(struct pool *, HANDLE hDevice);
! 355: #endif
! 356:
! 357: /* routines to deal with directories */
! 358: API_EXPORT(DIR *) ap_popendir(pool *p, const char *name);
! 359: API_EXPORT(void) ap_pclosedir(pool *p, DIR * d);
! 360:
! 361: /* ... even child processes (which we may want to wait for,
! 362: * or to kill outright, on unexpected termination).
! 363: *
! 364: * ap_spawn_child is a utility routine which handles an awful lot of
! 365: * the rigamarole associated with spawning a child --- it arranges
! 366: * for pipes to the child's stdin and stdout, if desired (if not,
! 367: * set the associated args to NULL). It takes as args a function
! 368: * to call in the child, and an argument to be passed to the function.
! 369: */
! 370:
! 371: enum kill_conditions {
! 372: kill_never, /* process is never sent any signals */
! 373: kill_always, /* process is sent SIGKILL on pool cleanup */
! 374: kill_after_timeout, /* SIGTERM, wait 3 seconds, SIGKILL */
! 375: just_wait, /* wait forever for the process to complete */
! 376: kill_only_once /* send SIGTERM and then wait */
! 377: };
! 378:
! 379: typedef struct child_info child_info;
! 380: API_EXPORT(void) ap_note_subprocess(pool *a, pid_t pid,
! 381: enum kill_conditions how);
! 382: API_EXPORT(int) ap_spawn_child(pool *, int (*)(void *, child_info *),
! 383: void *, enum kill_conditions,
! 384: FILE **pipe_in, FILE **pipe_out,
! 385: FILE **pipe_err);
! 386:
! 387: /* magic numbers --- min free bytes to consider a free pool block useable,
! 388: * and the min amount to allocate if we have to go to malloc() */
! 389:
! 390: #ifndef BLOCK_MINFREE
! 391: #define BLOCK_MINFREE 4096
! 392: #endif
! 393: #ifndef BLOCK_MINALLOC
! 394: #define BLOCK_MINALLOC 8192
! 395: #endif
! 396:
! 397: /* Finally, some accounting */
! 398:
! 399: API_EXPORT(long) ap_bytes_in_pool(pool *p);
! 400: API_EXPORT(long) ap_bytes_in_free_blocks(void);
! 401:
! 402: #ifdef __cplusplus
! 403: }
! 404: #endif
! 405:
! 406: #endif /* !APACHE_ALLOC_H */
E-mail:
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to ap_alloc.h CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [parser3project] / win32 / apache13 / src / include