Panda3D
|
00001 /* 00002 Default header file for malloc-2.8.x, written by Doug Lea 00003 and released to the public domain, as explained at 00004 http://creativecommons.org/licenses/publicdomain. 00005 00006 last update: Mon Aug 15 08:55:52 2005 Doug Lea (dl at gee) 00007 00008 This header is for ANSI C/C++ only. You can set any of 00009 the following #defines before including: 00010 00011 * If USE_DL_PREFIX is defined, it is assumed that malloc.c 00012 was also compiled with this option, so all routines 00013 have names starting with "dl". 00014 00015 * If HAVE_USR_INCLUDE_MALLOC_H is defined, it is assumed that this 00016 file will be #included AFTER <malloc.h>. This is needed only if 00017 your system defines a struct mallinfo that is incompatible with the 00018 standard one declared here. Otherwise, you can include this file 00019 INSTEAD of your system system <malloc.h>. At least on ANSI, all 00020 declarations should be compatible with system versions 00021 00022 * If MSPACES is defined, declarations for mspace versions are included. 00023 */ 00024 00025 #ifndef MALLOC_280_H 00026 #define MALLOC_280_H 00027 00028 #ifdef __cplusplus 00029 extern "C" { 00030 #endif 00031 00032 #include <stddef.h> /* for size_t */ 00033 00034 #if !ONLY_MSPACES 00035 00036 #ifndef USE_DL_PREFIX 00037 #define dlcalloc calloc 00038 #define dlfree free 00039 #define dlmalloc malloc 00040 #define dlmemalign memalign 00041 #define dlrealloc realloc 00042 #define dlvalloc valloc 00043 #define dlpvalloc pvalloc 00044 #define dlmallinfo mallinfo 00045 #define dlmallopt mallopt 00046 #define dlmalloc_trim malloc_trim 00047 #define dlmalloc_stats malloc_stats 00048 #define dlmalloc_usable_size malloc_usable_size 00049 #define dlmalloc_footprint malloc_footprint 00050 #define dlindependent_calloc independent_calloc 00051 #define dlindependent_comalloc independent_comalloc 00052 #endif /* USE_DL_PREFIX */ 00053 00054 00055 /* 00056 malloc(size_t n) 00057 Returns a pointer to a newly allocated chunk of at least n bytes, or 00058 null if no space is available, in which case errno is set to ENOMEM 00059 on ANSI C systems. 00060 00061 If n is zero, malloc returns a minimum-sized chunk. (The minimum 00062 size is 16 bytes on most 32bit systems, and 32 bytes on 64bit 00063 systems.) Note that size_t is an unsigned type, so calls with 00064 arguments that would be negative if signed are interpreted as 00065 requests for huge amounts of space, which will often fail. The 00066 maximum supported value of n differs across systems, but is in all 00067 cases less than the maximum representable value of a size_t. 00068 */ 00069 void* dlmalloc(size_t); 00070 00071 /* 00072 free(void* p) 00073 Releases the chunk of memory pointed to by p, that had been previously 00074 allocated using malloc or a related routine such as realloc. 00075 It has no effect if p is null. If p was not malloced or already 00076 freed, free(p) will by default cuase the current program to abort. 00077 */ 00078 void dlfree(void*); 00079 00080 /* 00081 calloc(size_t n_elements, size_t element_size); 00082 Returns a pointer to n_elements * element_size bytes, with all locations 00083 set to zero. 00084 */ 00085 void* dlcalloc(size_t, size_t); 00086 00087 /* 00088 realloc(void* p, size_t n) 00089 Returns a pointer to a chunk of size n that contains the same data 00090 as does chunk p up to the minimum of (n, p's size) bytes, or null 00091 if no space is available. 00092 00093 The returned pointer may or may not be the same as p. The algorithm 00094 prefers extending p in most cases when possible, otherwise it 00095 employs the equivalent of a malloc-copy-free sequence. 00096 00097 If p is null, realloc is equivalent to malloc. 00098 00099 If space is not available, realloc returns null, errno is set (if on 00100 ANSI) and p is NOT freed. 00101 00102 if n is for fewer bytes than already held by p, the newly unused 00103 space is lopped off and freed if possible. realloc with a size 00104 argument of zero (re)allocates a minimum-sized chunk. 00105 00106 The old unix realloc convention of allowing the last-free'd chunk 00107 to be used as an argument to realloc is not supported. 00108 */ 00109 00110 void* dlrealloc(void*, size_t); 00111 00112 /* 00113 memalign(size_t alignment, size_t n); 00114 Returns a pointer to a newly allocated chunk of n bytes, aligned 00115 in accord with the alignment argument. 00116 00117 The alignment argument should be a power of two. If the argument is 00118 not a power of two, the nearest greater power is used. 00119 8-byte alignment is guaranteed by normal malloc calls, so don't 00120 bother calling memalign with an argument of 8 or less. 00121 00122 Overreliance on memalign is a sure way to fragment space. 00123 */ 00124 void* dlmemalign(size_t, size_t); 00125 00126 /* 00127 valloc(size_t n); 00128 Equivalent to memalign(pagesize, n), where pagesize is the page 00129 size of the system. If the pagesize is unknown, 4096 is used. 00130 */ 00131 void* dlvalloc(size_t); 00132 00133 /* 00134 mallopt(int parameter_number, int parameter_value) 00135 Sets tunable parameters The format is to provide a 00136 (parameter-number, parameter-value) pair. mallopt then sets the 00137 corresponding parameter to the argument value if it can (i.e., so 00138 long as the value is meaningful), and returns 1 if successful else 00139 0. SVID/XPG/ANSI defines four standard param numbers for mallopt, 00140 normally defined in malloc.h. None of these are use in this malloc, 00141 so setting them has no effect. But this malloc also supports other 00142 options in mallopt: 00143 00144 Symbol param # default allowed param values 00145 M_TRIM_THRESHOLD -1 2*1024*1024 any (-1U disables trimming) 00146 M_GRANULARITY -2 page size any power of 2 >= page size 00147 M_MMAP_THRESHOLD -3 256*1024 any (or 0 if no MMAP support) 00148 */ 00149 int dlmallopt(int, int); 00150 00151 #define M_TRIM_THRESHOLD (-1) 00152 #define M_GRANULARITY (-2) 00153 #define M_MMAP_THRESHOLD (-3) 00154 00155 00156 /* 00157 malloc_footprint(); 00158 Returns the number of bytes obtained from the system. The total 00159 number of bytes allocated by malloc, realloc etc., is less than this 00160 value. Unlike mallinfo, this function returns only a precomputed 00161 result, so can be called frequently to monitor memory consumption. 00162 Even if locks are otherwise defined, this function does not use them, 00163 so results might not be up to date. 00164 */ 00165 size_t dlmalloc_footprint(); 00166 00167 #if !NO_MALLINFO 00168 /* 00169 mallinfo() 00170 Returns (by copy) a struct containing various summary statistics: 00171 00172 arena: current total non-mmapped bytes allocated from system 00173 ordblks: the number of free chunks 00174 smblks: always zero. 00175 hblks: current number of mmapped regions 00176 hblkhd: total bytes held in mmapped regions 00177 usmblks: the maximum total allocated space. This will be greater 00178 than current total if trimming has occurred. 00179 fsmblks: always zero 00180 uordblks: current total allocated space (normal or mmapped) 00181 fordblks: total free space 00182 keepcost: the maximum number of bytes that could ideally be released 00183 back to system via malloc_trim. ("ideally" means that 00184 it ignores page restrictions etc.) 00185 00186 Because these fields are ints, but internal bookkeeping may 00187 be kept as longs, the reported values may wrap around zero and 00188 thus be inaccurate. 00189 */ 00190 #ifndef HAVE_USR_INCLUDE_MALLOC_H 00191 #ifndef _MALLOC_H 00192 #ifndef MALLINFO_FIELD_TYPE 00193 #define MALLINFO_FIELD_TYPE size_t 00194 #endif /* MALLINFO_FIELD_TYPE */ 00195 struct mallinfo { 00196 MALLINFO_FIELD_TYPE arena; /* non-mmapped space allocated from system */ 00197 MALLINFO_FIELD_TYPE ordblks; /* number of free chunks */ 00198 MALLINFO_FIELD_TYPE smblks; /* always 0 */ 00199 MALLINFO_FIELD_TYPE hblks; /* always 0 */ 00200 MALLINFO_FIELD_TYPE hblkhd; /* space in mmapped regions */ 00201 MALLINFO_FIELD_TYPE usmblks; /* maximum total allocated space */ 00202 MALLINFO_FIELD_TYPE fsmblks; /* always 0 */ 00203 MALLINFO_FIELD_TYPE uordblks; /* total allocated space */ 00204 MALLINFO_FIELD_TYPE fordblks; /* total free space */ 00205 MALLINFO_FIELD_TYPE keepcost; /* releasable (via malloc_trim) space */ 00206 }; 00207 #endif /* _MALLOC_H */ 00208 #endif /* HAVE_USR_INCLUDE_MALLOC_H */ 00209 00210 struct mallinfo dlmallinfo(void); 00211 #endif /* NO_MALLINFO */ 00212 00213 /* 00214 independent_calloc(size_t n_elements, size_t element_size, void* chunks[]); 00215 00216 independent_calloc is similar to calloc, but instead of returning a 00217 single cleared space, it returns an array of pointers to n_elements 00218 independent elements that can hold contents of size elem_size, each 00219 of which starts out cleared, and can be independently freed, 00220 realloc'ed etc. The elements are guaranteed to be adjacently 00221 allocated (this is not guaranteed to occur with multiple callocs or 00222 mallocs), which may also improve cache locality in some 00223 applications. 00224 00225 The "chunks" argument is optional (i.e., may be null, which is 00226 probably the most typical usage). If it is null, the returned array 00227 is itself dynamically allocated and should also be freed when it is 00228 no longer needed. Otherwise, the chunks array must be of at least 00229 n_elements in length. It is filled in with the pointers to the 00230 chunks. 00231 00232 In either case, independent_calloc returns this pointer array, or 00233 null if the allocation failed. If n_elements is zero and "chunks" 00234 is null, it returns a chunk representing an array with zero elements 00235 (which should be freed if not wanted). 00236 00237 Each element must be individually freed when it is no longer 00238 needed. If you'd like to instead be able to free all at once, you 00239 should instead use regular calloc and assign pointers into this 00240 space to represent elements. (In this case though, you cannot 00241 independently free elements.) 00242 00243 independent_calloc simplifies and speeds up implementations of many 00244 kinds of pools. It may also be useful when constructing large data 00245 structures that initially have a fixed number of fixed-sized nodes, 00246 but the number is not known at compile time, and some of the nodes 00247 may later need to be freed. For example: 00248 00249 struct Node { int item; struct Node* next; }; 00250 00251 struct Node* build_list() { 00252 struct Node** pool; 00253 int n = read_number_of_nodes_needed(); 00254 if (n <= 0) return 0; 00255 pool = (struct Node**)(independent_calloc(n, sizeof(struct Node), 0); 00256 if (pool == 0) die(); 00257 // organize into a linked list... 00258 struct Node* first = pool[0]; 00259 for (i = 0; i < n-1; ++i) 00260 pool[i]->next = pool[i+1]; 00261 free(pool); // Can now free the array (or not, if it is needed later) 00262 return first; 00263 } 00264 */ 00265 void** dlindependent_calloc(size_t, size_t, void**); 00266 00267 /* 00268 independent_comalloc(size_t n_elements, size_t sizes[], void* chunks[]); 00269 00270 independent_comalloc allocates, all at once, a set of n_elements 00271 chunks with sizes indicated in the "sizes" array. It returns 00272 an array of pointers to these elements, each of which can be 00273 independently freed, realloc'ed etc. The elements are guaranteed to 00274 be adjacently allocated (this is not guaranteed to occur with 00275 multiple callocs or mallocs), which may also improve cache locality 00276 in some applications. 00277 00278 The "chunks" argument is optional (i.e., may be null). If it is null 00279 the returned array is itself dynamically allocated and should also 00280 be freed when it is no longer needed. Otherwise, the chunks array 00281 must be of at least n_elements in length. It is filled in with the 00282 pointers to the chunks. 00283 00284 In either case, independent_comalloc returns this pointer array, or 00285 null if the allocation failed. If n_elements is zero and chunks is 00286 null, it returns a chunk representing an array with zero elements 00287 (which should be freed if not wanted). 00288 00289 Each element must be individually freed when it is no longer 00290 needed. If you'd like to instead be able to free all at once, you 00291 should instead use a single regular malloc, and assign pointers at 00292 particular offsets in the aggregate space. (In this case though, you 00293 cannot independently free elements.) 00294 00295 independent_comallac differs from independent_calloc in that each 00296 element may have a different size, and also that it does not 00297 automatically clear elements. 00298 00299 independent_comalloc can be used to speed up allocation in cases 00300 where several structs or objects must always be allocated at the 00301 same time. For example: 00302 00303 struct Head { ... } 00304 struct Foot { ... } 00305 00306 void send_message(char* msg) { 00307 int msglen = strlen(msg); 00308 size_t sizes[3] = { sizeof(struct Head), msglen, sizeof(struct Foot) }; 00309 void* chunks[3]; 00310 if (independent_comalloc(3, sizes, chunks) == 0) 00311 die(); 00312 struct Head* head = (struct Head*)(chunks[0]); 00313 char* body = (char*)(chunks[1]); 00314 struct Foot* foot = (struct Foot*)(chunks[2]); 00315 // ... 00316 } 00317 00318 In general though, independent_comalloc is worth using only for 00319 larger values of n_elements. For small values, you probably won't 00320 detect enough difference from series of malloc calls to bother. 00321 00322 Overuse of independent_comalloc can increase overall memory usage, 00323 since it cannot reuse existing noncontiguous small chunks that 00324 might be available for some of the elements. 00325 */ 00326 void** dlindependent_comalloc(size_t, size_t*, void**); 00327 00328 00329 /* 00330 pvalloc(size_t n); 00331 Equivalent to valloc(minimum-page-that-holds(n)), that is, 00332 round up n to nearest pagesize. 00333 */ 00334 void* dlpvalloc(size_t); 00335 00336 /* 00337 malloc_trim(size_t pad); 00338 00339 If possible, gives memory back to the system (via negative arguments 00340 to sbrk) if there is unused memory at the `high' end of the malloc 00341 pool or in unused MMAP segments. You can call this after freeing 00342 large blocks of memory to potentially reduce the system-level memory 00343 requirements of a program. However, it cannot guarantee to reduce 00344 memory. Under some allocation patterns, some large free blocks of 00345 memory will be locked between two used chunks, so they cannot be 00346 given back to the system. 00347 00348 The `pad' argument to malloc_trim represents the amount of free 00349 trailing space to leave untrimmed. If this argument is zero, only 00350 the minimum amount of memory to maintain internal data structures 00351 will be left. Non-zero arguments can be supplied to maintain enough 00352 trailing space to service future expected allocations without having 00353 to re-obtain memory from the system. 00354 00355 Malloc_trim returns 1 if it actually released any memory, else 0. 00356 */ 00357 int dlmalloc_trim(size_t); 00358 00359 /* 00360 malloc_usable_size(void* p); 00361 00362 Returns the number of bytes you can actually use in 00363 an allocated chunk, which may be more than you requested (although 00364 often not) due to alignment and minimum size constraints. 00365 You can use this many bytes without worrying about 00366 overwriting other allocated objects. This is not a particularly great 00367 programming practice. malloc_usable_size can be more useful in 00368 debugging and assertions, for example: 00369 00370 p = malloc(n); 00371 assert(malloc_usable_size(p) >= 256); 00372 */ 00373 size_t dlmalloc_usable_size(void*); 00374 00375 /* 00376 malloc_stats(); 00377 Prints on stderr the amount of space obtained from the system (both 00378 via sbrk and mmap), the maximum amount (which may be more than 00379 current if malloc_trim and/or munmap got called), and the current 00380 number of bytes allocated via malloc (or realloc, etc) but not yet 00381 freed. Note that this is the number of bytes allocated, not the 00382 number requested. It will be larger than the number requested 00383 because of alignment and bookkeeping overhead. Because it includes 00384 alignment wastage as being in use, this figure may be greater than 00385 zero even when no user-level chunks are allocated. 00386 00387 The reported current and maximum system memory can be inaccurate if 00388 a program makes other calls to system memory allocation functions 00389 (normally sbrk) outside of malloc. 00390 00391 malloc_stats prints only the most commonly interesting statistics. 00392 More information can be obtained by calling mallinfo. 00393 */ 00394 void dlmalloc_stats(); 00395 00396 #endif /* !ONLY_MSPACES */ 00397 00398 #if MSPACES 00399 00400 /* 00401 mspace is an opaque type representing an independent 00402 region of space that supports mspace_malloc, etc. 00403 */ 00404 typedef void* mspace; 00405 00406 /* 00407 create_mspace creates and returns a new independent space with the 00408 given initial capacity, or, if 0, the default granularity size. It 00409 returns null if there is no system memory available to create the 00410 space. If argument locked is non-zero, the space uses a separate 00411 lock to control access. The capacity of the space will grow 00412 dynamically as needed to service mspace_malloc requests. You can 00413 control the sizes of incremental increases of this space by 00414 compiling with a different DEFAULT_GRANULARITY or dynamically 00415 setting with mallopt(M_GRANULARITY, value). 00416 */ 00417 mspace create_mspace(size_t capacity, int locked); 00418 00419 /* 00420 destroy_mspace destroys the given space, and attempts to return all 00421 of its memory back to the system, returning the total number of 00422 bytes freed. After destruction, the results of access to all memory 00423 used by the space become undefined. 00424 */ 00425 size_t destroy_mspace(mspace msp); 00426 00427 /* 00428 create_mspace_with_base uses the memory supplied as the initial base 00429 of a new mspace. Part (less than 128*sizeof(size_t) bytes) of this 00430 space is used for bookkeeping, so the capacity must be at least this 00431 large. (Otherwise 0 is returned.) When this initial space is 00432 exhausted, additional memory will be obtained from the system. 00433 Destroying this space will deallocate all additionally allocated 00434 space (if possible) but not the initial base. 00435 */ 00436 mspace create_mspace_with_base(void* base, size_t capacity, int locked); 00437 00438 /* 00439 mspace_malloc behaves as malloc, but operates within 00440 the given space. 00441 */ 00442 void* mspace_malloc(mspace msp, size_t bytes); 00443 00444 /* 00445 mspace_free behaves as free, but operates within 00446 the given space. 00447 00448 If compiled with FOOTERS==1, mspace_free is not actually needed. 00449 free may be called instead of mspace_free because freed chunks from 00450 any space are handled by their originating spaces. 00451 */ 00452 void mspace_free(mspace msp, void* mem); 00453 00454 /* 00455 mspace_realloc behaves as realloc, but operates within 00456 the given space. 00457 00458 If compiled with FOOTERS==1, mspace_realloc is not actually 00459 needed. realloc may be called instead of mspace_realloc because 00460 realloced chunks from any space are handled by their originating 00461 spaces. 00462 */ 00463 void* mspace_realloc(mspace msp, void* mem, size_t newsize); 00464 00465 /* 00466 mspace_calloc behaves as calloc, but operates within 00467 the given space. 00468 */ 00469 void* mspace_calloc(mspace msp, size_t n_elements, size_t elem_size); 00470 00471 /* 00472 mspace_memalign behaves as memalign, but operates within 00473 the given space. 00474 */ 00475 void* mspace_memalign(mspace msp, size_t alignment, size_t bytes); 00476 00477 /* 00478 mspace_independent_calloc behaves as independent_calloc, but 00479 operates within the given space. 00480 */ 00481 void** mspace_independent_calloc(mspace msp, size_t n_elements, 00482 size_t elem_size, void* chunks[]); 00483 00484 /* 00485 mspace_independent_comalloc behaves as independent_comalloc, but 00486 operates within the given space. 00487 */ 00488 void** mspace_independent_comalloc(mspace msp, size_t n_elements, 00489 size_t sizes[], void* chunks[]); 00490 00491 /* 00492 mspace_footprint() returns the number of bytes obtained from the 00493 system for this space. 00494 */ 00495 size_t mspace_footprint(mspace msp); 00496 00497 00498 #if !NO_MALLINFO 00499 /* 00500 mspace_mallinfo behaves as mallinfo, but reports properties of 00501 the given space. 00502 */ 00503 struct mallinfo mspace_mallinfo(mspace msp); 00504 #endif /* NO_MALLINFO */ 00505 00506 /* 00507 mspace_malloc_stats behaves as malloc_stats, but reports 00508 properties of the given space. 00509 */ 00510 void mspace_malloc_stats(mspace msp); 00511 00512 /* 00513 mspace_trim behaves as malloc_trim, but 00514 operates within the given space. 00515 */ 00516 int mspace_trim(mspace msp, size_t pad); 00517 00518 /* 00519 An alias for mallopt. 00520 */ 00521 int mspace_mallopt(int, int); 00522 00523 #endif /* MSPACES */ 00524 00525 #ifdef __cplusplus 00526 }; /* end of extern "C" */ 00527 #endif 00528 00529 #endif /* MALLOC_280_H */