Clean up dlmalloc.
[wincetools.git] / loader / dlmalloc.h
1 #ifndef USE_DL_PREFIX
2 #define USE_DL_PREFIX 1
3 #endif
4
5 /*
6   Default header file for malloc-2.8.x, written by Doug Lea
7   and released to the public domain, as explained at
8   http://creativecommons.org/licenses/publicdomain. 
9  
10   last update: Wed May 27 14:25:17 2009  Doug Lea  (dl at gee)
11
12   This header is for ANSI C/C++ only.  You can set any of
13   the following #defines before including:
14
15   * If USE_DL_PREFIX is defined, it is assumed that malloc.c 
16     was also compiled with this option, so all routines
17     have names starting with "dl".
18
19   * If HAVE_USR_INCLUDE_MALLOC_H is defined, it is assumed that this
20     file will be #included AFTER <malloc.h>. This is needed only if
21     your system defines a struct mallinfo that is incompatible with the
22     standard one declared here.  Otherwise, you can include this file
23     INSTEAD of your system system <malloc.h>.  At least on ANSI, all
24     declarations should be compatible with system versions
25
26   * If MSPACES is defined, declarations for mspace versions are included.
27 */
28
29 #ifndef MALLOC_280_H
30 #define MALLOC_280_H
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 #include <stddef.h>   /* for size_t */
37
38 #ifndef ONLY_MSPACES
39 #define ONLY_MSPACES 0     /* define to a value */
40 #endif  /* ONLY_MSPACES */
41 #ifndef NO_MALLINFO
42 #define NO_MALLINFO 0
43 #endif  /* NO_MALLINFO */
44
45
46 #if !ONLY_MSPACES
47
48 #ifndef USE_DL_PREFIX
49 #define dlcalloc               calloc
50 #define dlfree                 free
51 #define dlmalloc               malloc
52 #define dlmemalign             memalign
53 #define dlrealloc              realloc
54 #define dlvalloc               valloc
55 #define dlpvalloc              pvalloc
56 #define dlmallinfo             mallinfo
57 #define dlmallopt              mallopt
58 #define dlmalloc_trim          malloc_trim
59 #define dlmalloc_stats         malloc_stats
60 #define dlmalloc_usable_size   malloc_usable_size
61 #define dlmalloc_footprint     malloc_footprint
62 #define dlindependent_calloc   independent_calloc
63 #define dlindependent_comalloc independent_comalloc
64 #endif /* USE_DL_PREFIX */
65 #if !NO_MALLINFO 
66 #ifndef HAVE_USR_INCLUDE_MALLOC_H
67 #ifndef _MALLOC_H
68 #ifndef MALLINFO_FIELD_TYPE
69 #define MALLINFO_FIELD_TYPE size_t
70 #endif /* MALLINFO_FIELD_TYPE */
71 #ifndef STRUCT_MALLINFO_DECLARED
72 #define STRUCT_MALLINFO_DECLARED 1
73 struct mallinfo {
74   MALLINFO_FIELD_TYPE arena;    /* non-mmapped space allocated from system */
75   MALLINFO_FIELD_TYPE ordblks;  /* number of free chunks */
76   MALLINFO_FIELD_TYPE smblks;   /* always 0 */
77   MALLINFO_FIELD_TYPE hblks;    /* always 0 */
78   MALLINFO_FIELD_TYPE hblkhd;   /* space in mmapped regions */
79   MALLINFO_FIELD_TYPE usmblks;  /* maximum total allocated space */
80   MALLINFO_FIELD_TYPE fsmblks;  /* always 0 */
81   MALLINFO_FIELD_TYPE uordblks; /* total allocated space */
82   MALLINFO_FIELD_TYPE fordblks; /* total free space */
83   MALLINFO_FIELD_TYPE keepcost; /* releasable (via malloc_trim) space */
84 };
85 #endif /* STRUCT_MALLINFO_DECLARED */
86 #endif  /* _MALLOC_H */
87 #endif  /* HAVE_USR_INCLUDE_MALLOC_H */
88 #endif  /* !NO_MALLINFO */
89
90 /*
91   malloc(size_t n)
92   Returns a pointer to a newly allocated chunk of at least n bytes, or
93   null if no space is available, in which case errno is set to ENOMEM
94   on ANSI C systems.
95
96   If n is zero, malloc returns a minimum-sized chunk. (The minimum
97   size is 16 bytes on most 32bit systems, and 32 bytes on 64bit
98   systems.)  Note that size_t is an unsigned type, so calls with
99   arguments that would be negative if signed are interpreted as
100   requests for huge amounts of space, which will often fail. The
101   maximum supported value of n differs across systems, but is in all
102   cases less than the maximum representable value of a size_t.
103 */
104 void* dlmalloc(size_t);
105
106 /*
107   free(void* p)
108   Releases the chunk of memory pointed to by p, that had been previously
109   allocated using malloc or a related routine such as realloc.
110   It has no effect if p is null. If p was not malloced or already
111   freed, free(p) will by default cuase the current program to abort.
112 */
113 void  dlfree(void*);
114
115 /*
116   calloc(size_t n_elements, size_t element_size);
117   Returns a pointer to n_elements * element_size bytes, with all locations
118   set to zero.
119 */
120 void* dlcalloc(size_t, size_t);
121
122 /*
123   realloc(void* p, size_t n)
124   Returns a pointer to a chunk of size n that contains the same data
125   as does chunk p up to the minimum of (n, p's size) bytes, or null
126   if no space is available.
127
128   The returned pointer may or may not be the same as p. The algorithm
129   prefers extending p in most cases when possible, otherwise it
130   employs the equivalent of a malloc-copy-free sequence.
131
132   If p is null, realloc is equivalent to malloc.
133
134   If space is not available, realloc returns null, errno is set (if on
135   ANSI) and p is NOT freed.
136
137   if n is for fewer bytes than already held by p, the newly unused
138   space is lopped off and freed if possible.  realloc with a size
139   argument of zero (re)allocates a minimum-sized chunk.
140
141   The old unix realloc convention of allowing the last-free'd chunk
142   to be used as an argument to realloc is not supported.
143 */
144
145 void* dlrealloc(void*, size_t);
146
147 /*
148   memalign(size_t alignment, size_t n);
149   Returns a pointer to a newly allocated chunk of n bytes, aligned
150   in accord with the alignment argument.
151
152   The alignment argument should be a power of two. If the argument is
153   not a power of two, the nearest greater power is used.
154   8-byte alignment is guaranteed by normal malloc calls, so don't
155   bother calling memalign with an argument of 8 or less.
156
157   Overreliance on memalign is a sure way to fragment space.
158 */
159 void* dlmemalign(size_t, size_t);
160
161 /*
162   valloc(size_t n);
163   Equivalent to memalign(pagesize, n), where pagesize is the page
164   size of the system. If the pagesize is unknown, 4096 is used.
165 */
166 void* dlvalloc(size_t);
167
168 /*
169   mallopt(int parameter_number, int parameter_value)
170   Sets tunable parameters The format is to provide a
171   (parameter-number, parameter-value) pair.  mallopt then sets the
172   corresponding parameter to the argument value if it can (i.e., so
173   long as the value is meaningful), and returns 1 if successful else
174   0.  SVID/XPG/ANSI defines four standard param numbers for mallopt,
175   normally defined in malloc.h.  None of these are use in this malloc,
176   so setting them has no effect. But this malloc also supports other
177   options in mallopt:
178
179   Symbol            param #  default    allowed param values
180   M_TRIM_THRESHOLD     -1   2*1024*1024   any   (-1U disables trimming)
181   M_GRANULARITY        -2     page size   any power of 2 >= page size
182   M_MMAP_THRESHOLD     -3      256*1024   any   (or 0 if no MMAP support)
183 */
184 int dlmallopt(int, int);
185
186 #define M_TRIM_THRESHOLD     (-1)
187 #define M_GRANULARITY        (-2)
188 #define M_MMAP_THRESHOLD     (-3)
189
190
191 /*
192   malloc_footprint();
193   Returns the number of bytes obtained from the system.  The total
194   number of bytes allocated by malloc, realloc etc., is less than this
195   value. Unlike mallinfo, this function returns only a precomputed
196   result, so can be called frequently to monitor memory consumption.
197   Even if locks are otherwise defined, this function does not use them,
198   so results might not be up to date.
199 */
200 size_t dlmalloc_footprint();
201
202 #if !NO_MALLINFO
203 /*
204   mallinfo()
205   Returns (by copy) a struct containing various summary statistics:
206
207   arena:     current total non-mmapped bytes allocated from system
208   ordblks:   the number of free chunks
209   smblks:    always zero.
210   hblks:     current number of mmapped regions
211   hblkhd:    total bytes held in mmapped regions
212   usmblks:   the maximum total allocated space. This will be greater
213                 than current total if trimming has occurred.
214   fsmblks:   always zero
215   uordblks:  current total allocated space (normal or mmapped)
216   fordblks:  total free space
217   keepcost:  the maximum number of bytes that could ideally be released
218                back to system via malloc_trim. ("ideally" means that
219                it ignores page restrictions etc.)
220
221   Because these fields are ints, but internal bookkeeping may
222   be kept as longs, the reported values may wrap around zero and
223   thus be inaccurate.
224 */
225
226 struct mallinfo dlmallinfo(void);
227 #endif  /* NO_MALLINFO */
228
229 /*
230   independent_calloc(size_t n_elements, size_t element_size, void* chunks[]);
231
232   independent_calloc is similar to calloc, but instead of returning a
233   single cleared space, it returns an array of pointers to n_elements
234   independent elements that can hold contents of size elem_size, each
235   of which starts out cleared, and can be independently freed,
236   realloc'ed etc. The elements are guaranteed to be adjacently
237   allocated (this is not guaranteed to occur with multiple callocs or
238   mallocs), which may also improve cache locality in some
239   applications.
240
241   The "chunks" argument is optional (i.e., may be null, which is
242   probably the most typical usage). If it is null, the returned array
243   is itself dynamically allocated and should also be freed when it is
244   no longer needed. Otherwise, the chunks array must be of at least
245   n_elements in length. It is filled in with the pointers to the
246   chunks.
247
248   In either case, independent_calloc returns this pointer array, or
249   null if the allocation failed.  If n_elements is zero and "chunks"
250   is null, it returns a chunk representing an array with zero elements
251   (which should be freed if not wanted).
252
253   Each element must be individually freed when it is no longer
254   needed. If you'd like to instead be able to free all at once, you
255   should instead use regular calloc and assign pointers into this
256   space to represent elements.  (In this case though, you cannot
257   independently free elements.)
258
259   independent_calloc simplifies and speeds up implementations of many
260   kinds of pools.  It may also be useful when constructing large data
261   structures that initially have a fixed number of fixed-sized nodes,
262   but the number is not known at compile time, and some of the nodes
263   may later need to be freed. For example:
264
265   struct Node { int item; struct Node* next; };
266
267   struct Node* build_list() {
268     struct Node** pool;
269     int n = read_number_of_nodes_needed();
270     if (n <= 0) return 0;
271     pool = (struct Node**)(independent_calloc(n, sizeof(struct Node), 0);
272     if (pool == 0) die();
273     // organize into a linked list...
274     struct Node* first = pool[0];
275     for (i = 0; i < n-1; ++i)
276       pool[i]->next = pool[i+1];
277     free(pool);     // Can now free the array (or not, if it is needed later)
278     return first;
279   }
280 */
281 void** dlindependent_calloc(size_t, size_t, void**);
282
283 /*
284   independent_comalloc(size_t n_elements, size_t sizes[], void* chunks[]);
285
286   independent_comalloc allocates, all at once, a set of n_elements
287   chunks with sizes indicated in the "sizes" array.    It returns
288   an array of pointers to these elements, each of which can be
289   independently freed, realloc'ed etc. The elements are guaranteed to
290   be adjacently allocated (this is not guaranteed to occur with
291   multiple callocs or mallocs), which may also improve cache locality
292   in some applications.
293
294   The "chunks" argument is optional (i.e., may be null). If it is null
295   the returned array is itself dynamically allocated and should also
296   be freed when it is no longer needed. Otherwise, the chunks array
297   must be of at least n_elements in length. It is filled in with the
298   pointers to the chunks.
299
300   In either case, independent_comalloc returns this pointer array, or
301   null if the allocation failed.  If n_elements is zero and chunks is
302   null, it returns a chunk representing an array with zero elements
303   (which should be freed if not wanted).
304
305   Each element must be individually freed when it is no longer
306   needed. If you'd like to instead be able to free all at once, you
307   should instead use a single regular malloc, and assign pointers at
308   particular offsets in the aggregate space. (In this case though, you
309   cannot independently free elements.)
310
311   independent_comallac differs from independent_calloc in that each
312   element may have a different size, and also that it does not
313   automatically clear elements.
314
315   independent_comalloc can be used to speed up allocation in cases
316   where several structs or objects must always be allocated at the
317   same time.  For example:
318
319   struct Head { ... }
320   struct Foot { ... }
321
322   void send_message(char* msg) {
323     int msglen = strlen(msg);
324     size_t sizes[3] = { sizeof(struct Head), msglen, sizeof(struct Foot) };
325     void* chunks[3];
326     if (independent_comalloc(3, sizes, chunks) == 0)
327       die();
328     struct Head* head = (struct Head*)(chunks[0]);
329     char*        body = (char*)(chunks[1]);
330     struct Foot* foot = (struct Foot*)(chunks[2]);
331     // ...
332   }
333
334   In general though, independent_comalloc is worth using only for
335   larger values of n_elements. For small values, you probably won't
336   detect enough difference from series of malloc calls to bother.
337
338   Overuse of independent_comalloc can increase overall memory usage,
339   since it cannot reuse existing noncontiguous small chunks that
340   might be available for some of the elements.
341 */
342 void** dlindependent_comalloc(size_t, size_t*, void**);
343
344
345 /*
346   pvalloc(size_t n);
347   Equivalent to valloc(minimum-page-that-holds(n)), that is,
348   round up n to nearest pagesize.
349  */
350 void*  dlpvalloc(size_t);
351
352 /*
353   malloc_trim(size_t pad);
354
355   If possible, gives memory back to the system (via negative arguments
356   to sbrk) if there is unused memory at the `high' end of the malloc
357   pool or in unused MMAP segments. You can call this after freeing
358   large blocks of memory to potentially reduce the system-level memory
359   requirements of a program. However, it cannot guarantee to reduce
360   memory. Under some allocation patterns, some large free blocks of
361   memory will be locked between two used chunks, so they cannot be
362   given back to the system.
363
364   The `pad' argument to malloc_trim represents the amount of free
365   trailing space to leave untrimmed. If this argument is zero, only
366   the minimum amount of memory to maintain internal data structures
367   will be left. Non-zero arguments can be supplied to maintain enough
368   trailing space to service future expected allocations without having
369   to re-obtain memory from the system.
370
371   Malloc_trim returns 1 if it actually released any memory, else 0.
372 */
373 int  dlmalloc_trim(size_t);
374
375 /*
376   malloc_stats();
377   Prints on stderr the amount of space obtained from the system (both
378   via sbrk and mmap), the maximum amount (which may be more than
379   current if malloc_trim and/or munmap got called), and the current
380   number of bytes allocated via malloc (or realloc, etc) but not yet
381   freed. Note that this is the number of bytes allocated, not the
382   number requested. It will be larger than the number requested
383   because of alignment and bookkeeping overhead. Because it includes
384   alignment wastage as being in use, this figure may be greater than
385   zero even when no user-level chunks are allocated.
386
387   The reported current and maximum system memory can be inaccurate if
388   a program makes other calls to system memory allocation functions
389   (normally sbrk) outside of malloc.
390
391   malloc_stats prints only the most commonly interesting statistics.
392   More information can be obtained by calling mallinfo.
393 */
394 void  dlmalloc_stats();
395
396 #endif /* !ONLY_MSPACES */
397
398 /*
399   malloc_usable_size(void* p);
400
401   Returns the number of bytes you can actually use in
402   an allocated chunk, which may be more than you requested (although
403   often not) due to alignment and minimum size constraints.
404   You can use this many bytes without worrying about
405   overwriting other allocated objects. This is not a particularly great
406   programming practice. malloc_usable_size can be more useful in
407   debugging and assertions, for example:
408
409   p = malloc(n);
410   assert(malloc_usable_size(p) >= 256);
411 */
412 size_t dlmalloc_usable_size(void*);
413
414
415 #if MSPACES
416
417 /*
418   mspace is an opaque type representing an independent
419   region of space that supports mspace_malloc, etc.
420 */
421 typedef void* mspace;
422
423 /*
424   create_mspace creates and returns a new independent space with the
425   given initial capacity, or, if 0, the default granularity size.  It
426   returns null if there is no system memory available to create the
427   space.  If argument locked is non-zero, the space uses a separate
428   lock to control access. The capacity of the space will grow
429   dynamically as needed to service mspace_malloc requests.  You can
430   control the sizes of incremental increases of this space by
431   compiling with a different DEFAULT_GRANULARITY or dynamically
432   setting with mallopt(M_GRANULARITY, value).
433 */
434 mspace create_mspace(size_t capacity, int locked);
435
436 /*
437   destroy_mspace destroys the given space, and attempts to return all
438   of its memory back to the system, returning the total number of
439   bytes freed. After destruction, the results of access to all memory
440   used by the space become undefined.
441 */
442 size_t destroy_mspace(mspace msp);
443
444 /*
445   create_mspace_with_base uses the memory supplied as the initial base
446   of a new mspace. Part (less than 128*sizeof(size_t) bytes) of this
447   space is used for bookkeeping, so the capacity must be at least this
448   large. (Otherwise 0 is returned.) When this initial space is
449   exhausted, additional memory will be obtained from the system.
450   Destroying this space will deallocate all additionally allocated
451   space (if possible) but not the initial base.
452 */
453 mspace create_mspace_with_base(void* base, size_t capacity, int locked);
454
455 /*
456   mspace_track_large_chunks controls whether requests for large chunks
457   are allocated in their own untracked mmapped regions, separate from
458   others in this mspace. By default large chunks are not tracked,
459   which reduces fragmentation. However, such chunks are not
460   necessarily released to the system upon destroy_mspace.  Enabling
461   tracking by setting to true may increase fragmentation, but avoids
462   leakage when relying on destroy_mspace to release all memory
463   allocated using this space.  The function returns the previous
464   setting.
465 */
466 int mspace_track_large_chunks(mspace msp, int enable);
467
468 /*
469   mspace_malloc behaves as malloc, but operates within
470   the given space.
471 */
472 void* mspace_malloc(mspace msp, size_t bytes);
473
474 /*
475   mspace_free behaves as free, but operates within
476   the given space.
477
478   If compiled with FOOTERS==1, mspace_free is not actually needed.
479   free may be called instead of mspace_free because freed chunks from
480   any space are handled by their originating spaces.
481 */
482 void mspace_free(mspace msp, void* mem);
483
484 /*
485   mspace_realloc behaves as realloc, but operates within
486   the given space.
487
488   If compiled with FOOTERS==1, mspace_realloc is not actually
489   needed.  realloc may be called instead of mspace_realloc because
490   realloced chunks from any space are handled by their originating
491   spaces.
492 */
493 void* mspace_realloc(mspace msp, void* mem, size_t newsize);
494
495 /*
496   mspace_calloc behaves as calloc, but operates within
497   the given space.
498 */
499 void* mspace_calloc(mspace msp, size_t n_elements, size_t elem_size);
500
501 /*
502   mspace_memalign behaves as memalign, but operates within
503   the given space.
504 */
505 void* mspace_memalign(mspace msp, size_t alignment, size_t bytes);
506
507 /*
508   mspace_independent_calloc behaves as independent_calloc, but
509   operates within the given space.
510 */
511 void** mspace_independent_calloc(mspace msp, size_t n_elements,
512                                  size_t elem_size, void* chunks[]);
513
514 /*
515   mspace_independent_comalloc behaves as independent_comalloc, but
516   operates within the given space.
517 */
518 void** mspace_independent_comalloc(mspace msp, size_t n_elements,
519                                    size_t sizes[], void* chunks[]);
520
521 /*
522   mspace_footprint() returns the number of bytes obtained from the
523   system for this space.
524 */
525 size_t mspace_footprint(mspace msp);
526
527
528 #if !NO_MALLINFO
529 /*
530   mspace_mallinfo behaves as mallinfo, but reports properties of
531   the given space.
532 */
533 struct mallinfo mspace_mallinfo(mspace msp);
534 #endif /* NO_MALLINFO */
535
536 /*
537   malloc_usable_size(void* p) behaves the same as malloc_usable_size;
538 */
539  size_t mspace_usable_size(void* mem);
540
541 /*
542   mspace_malloc_stats behaves as malloc_stats, but reports
543   properties of the given space.
544 */
545 void mspace_malloc_stats(mspace msp);
546
547 /*
548   mspace_trim behaves as malloc_trim, but
549   operates within the given space.
550 */
551 int mspace_trim(mspace msp, size_t pad);
552
553 /*
554   An alias for mallopt.
555 */
556 int mspace_mallopt(int, int);
557
558 #endif  /* MSPACES */
559
560 #ifdef __cplusplus
561 };  /* end of extern "C" */
562 #endif
563
564 #endif /* MALLOC_280_H */