include/malloc/malloc.h

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 #ifndef _MALLOC_MALLOC_H_
  25 #define _MALLOC_MALLOC_H_
  26
  27 #include <stddef.h>
  28 #include <mach/mach_types.h>
  29 #include <sys/cdefs.h>
  30 #include <Availability.h>
  31
  32 __BEGIN_DECLS
  33 /*********      Type definitions        ************/
  34
  35 typedef struct _malloc_zone_t {
  36     /* Only zone implementors should depend on the layout of this structure;
  37     Regular callers should use the access functions below */
  38     void        *reserved1;     /* RESERVED FOR CFAllocator DO NOT USE */
  39     void        *reserved2;     /* RESERVED FOR CFAllocator DO NOT USE */
  40     size_t      (*size)(struct _malloc_zone_t *zone, const void *ptr); /* returns the size of a block or 0 if not in this zone; must be fast, especially for negative answers */
  41     void        *(*malloc)(struct _malloc_zone_t *zone, size_t size);
  42     void        *(*calloc)(struct _malloc_zone_t *zone, size_t num_items, size_t size); /* same as malloc, but block returned is set to zero */
  43     void        *(*valloc)(struct _malloc_zone_t *zone, size_t size); /* same as malloc, but block returned is set to zero and is guaranteed to be page aligned */
  44     void        (*free)(struct _malloc_zone_t *zone, void *ptr);
  45     void        *(*realloc)(struct _malloc_zone_t *zone, void *ptr, size_t size);
  46     void        (*destroy)(struct _malloc_zone_t *zone); /* zone is destroyed and all memory reclaimed */
  47     const char  *zone_name;
  48
  49     /* Optional batch callbacks; these may be NULL */
  50     unsigned    (*batch_malloc)(struct _malloc_zone_t *zone, size_t size, void **results, unsigned num_requested); /* given a size, returns pointers capable of holding that size; returns the number of pointers allocated (maybe 0 or less than num_requested) */
  51     void        (*batch_free)(struct _malloc_zone_t *zone, void **to_be_freed, unsigned num_to_be_freed); /* frees all the pointers in to_be_freed; note that to_be_freed may be overwritten during the process */
  52
  53     struct malloc_introspection_t       *introspect;
  54     unsigned    version;
  55
  56     /* aligned memory allocation. The callback may be NULL. Present in version >= 5. */
  57     void *(*memalign)(struct _malloc_zone_t *zone, size_t alignment, size_t size);
  58
  59     /* free a pointer known to be in zone and known to have the given size. The callback may be NULL. Present in version >= 6.*/
  60     void (*free_definite_size)(struct _malloc_zone_t *zone, void *ptr, size_t size);
  61
  62     /* Empty out caches in the face of memory pressure. The callback may be NULL. Present in version >= 8. */
  63     size_t      (*pressure_relief)(struct _malloc_zone_t *zone, size_t goal);
  64 } malloc_zone_t;
  65
  66 /*********      Creation and destruction        ************/
  67
  68 extern malloc_zone_t *malloc_default_zone(void);
  69     /* The initial zone */
  70
  71 extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags);
  72     /* Creates a new zone with default behavior and registers it */
  73
  74 extern void malloc_destroy_zone(malloc_zone_t *zone);
  75     /* Destroys zone and everything it allocated */
  76
  77 /*********      Block creation and manipulation ************/
  78
  79 extern void *malloc_zone_malloc(malloc_zone_t *zone, size_t size);
  80     /* Allocates a new pointer of size size; zone must be non-NULL */
  81
  82 extern void *malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size);
  83     /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */
  84
  85 extern void *malloc_zone_valloc(malloc_zone_t *zone, size_t size);
  86     /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */
  87
  88 extern void malloc_zone_free(malloc_zone_t *zone, void *ptr);
  89     /* Frees pointer in zone; zone must be non-NULL */
  90
  91 extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size);
  92     /* Enlarges block if necessary; zone must be non-NULL */
  93
  94 extern malloc_zone_t *malloc_zone_from_ptr(const void *ptr);
  95     /* Returns the zone for a pointer, or NULL if not in any zone.
  96     The ptr must have been returned from a malloc or realloc call. */
  97
  98 extern size_t malloc_size(const void *ptr);
  99     /* Returns size of given ptr */
 100
 101 extern size_t malloc_good_size(size_t size);
 102     /* Returns number of bytes greater than or equal to size that can be allocated without padding */
 103
 104 extern void *malloc_zone_memalign(malloc_zone_t *zone, size_t alignment, size_t size) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
 105     /*
 106      * Allocates a new pointer of size size whose address is an exact multiple of alignment.
 107      * alignment must be a power of two and at least as large as sizeof(void *).
 108      * zone must be non-NULL.
 109      */
 110
 111 /*********      Batch methods   ************/
 112
 113 extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void **results, unsigned num_requested);
 114     /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */
 115
 116 extern void malloc_zone_batch_free(malloc_zone_t *zone, void **to_be_freed, unsigned num);
 117     /* frees all the pointers in to_be_freed; note that to_be_freed may be overwritten during the process; This function will always free even if the zone has no batch callback */
 118
 119 /*********      Functions for libcache  ************/
 120
 121 extern malloc_zone_t *malloc_default_purgeable_zone(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
 122     /* Returns a pointer to the default purgeable_zone. */
 123
 124 extern void malloc_make_purgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
 125     /* Make an allocation from the purgeable zone purgeable if possible.  */
 126
 127 extern int malloc_make_nonpurgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);
 128     /* Makes an allocation from the purgeable zone nonpurgeable.
 129      * Returns zero if the contents were not purged since the last
 130      * call to malloc_make_purgeable, else returns non-zero. */
 131
 132 /*********      Functions for zone implementors ************/
 133
 134 extern void malloc_zone_register(malloc_zone_t *zone);
 135     /* Registers a custom malloc zone; Should typically be called after a
 136      * malloc_zone_t has been filled in with custom methods by a client.  See
 137      * malloc_create_zone for creating additional malloc zones with the
 138      * default allocation and free behavior. */
 139
 140 extern void malloc_zone_unregister(malloc_zone_t *zone);
 141     /* De-registers a zone
 142     Should typically be called before calling the zone destruction routine */
 143
 144 extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name);
 145     /* Sets the name of a zone */
 146
 147 extern const char *malloc_get_zone_name(malloc_zone_t *zone);
 148     /* Returns the name of a zone */
 149
 150 size_t malloc_zone_pressure_relief(malloc_zone_t *zone, size_t goal) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 151     /* malloc_zone_pressure_relief() advises the malloc subsystem that the process is under memory pressure and
 152      * that the subsystem should make its best effort towards releasing (i.e. munmap()-ing) "goal" bytes from "zone".
 153      * If "goal" is passed as zero, the malloc subsystem will attempt to achieve maximal pressure relief in "zone".
 154      * If "zone" is passed as NULL, all zones are examined for pressure relief opportunities.
 155      * malloc_zone_pressure_relief() returns the number of bytes released.
 156      */
 157
 158 typedef struct {
 159     vm_address_t        address;
 160     vm_size_t           size;
 161 } vm_range_t;
 162
 163 typedef struct malloc_statistics_t {
 164     unsigned    blocks_in_use;
 165     size_t      size_in_use;
 166     size_t      max_size_in_use;        /* high water mark of touched memory */
 167     size_t      size_allocated;         /* reserved in memory */
 168 } malloc_statistics_t;
 169
 170 typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory);
 171     /* given a task, "reads" the memory at the given address and size
 172 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */
 173
 174 #define MALLOC_PTR_IN_USE_RANGE_TYPE    1       /* for allocated pointers */
 175 #define MALLOC_PTR_REGION_RANGE_TYPE    2       /* for region containing pointers */
 176 #define MALLOC_ADMIN_REGION_RANGE_TYPE  4       /* for region used internally */
 177 #define MALLOC_ZONE_SPECIFIC_FLAGS      0xff00  /* bits reserved for zone-specific purposes */
 178
 179 typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);
 180     /* given a task and context, "records" the specified addresses */
 181
 182 typedef struct malloc_introspection_t {
 183     kern_return_t (*enumerator)(task_t task, void *, unsigned type_mask, vm_address_t zone_address, memory_reader_t reader, vm_range_recorder_t recorder); /* enumerates all the malloc pointers in use */
 184     size_t      (*good_size)(malloc_zone_t *zone, size_t size);
 185     boolean_t   (*check)(malloc_zone_t *zone); /* Consistency checker */
 186     void        (*print)(malloc_zone_t *zone, boolean_t verbose); /* Prints zone  */
 187     void        (*log)(malloc_zone_t *zone, void *address); /* Enables logging of activity */
 188     void        (*force_lock)(malloc_zone_t *zone); /* Forces locking zone */
 189     void        (*force_unlock)(malloc_zone_t *zone); /* Forces unlocking zone */
 190     void        (*statistics)(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */
 191     boolean_t   (*zone_locked)(malloc_zone_t *zone); /* Are any zone locks held */
 192
 193     /* Discharge checking. Present in version >= 7. */
 194     boolean_t   (*enable_discharge_checking)(malloc_zone_t *zone);
 195     void        (*disable_discharge_checking)(malloc_zone_t *zone);
 196     void        (*discharge)(malloc_zone_t *zone, void *memory);
 197 #ifdef __BLOCKS__
 198     void        (*enumerate_discharged_pointers)(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info));
 199 #else
 200     void        *enumerate_unavailable_without_blocks;
 201 #endif /* __BLOCKS__ */
 202 } malloc_introspection_t;
 203
 204 extern void malloc_printf(const char *format, ...);
 205     /* Convenience for logging errors and warnings;
 206     No allocation is performed during execution of this function;
 207     Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...)
 208     */
 209
 210 /*********      Functions for performance tools ************/
 211
 212 extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count);
 213     /* Fills addresses and count with the addresses of the zones in task;
 214     Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */
 215
 216 /*********      Debug helpers   ************/
 217
 218 extern void malloc_zone_print_ptr_info(void *ptr);
 219     /* print to stdout if this pointer is in the malloc heap, free status, and size */
 220
 221 extern boolean_t malloc_zone_check(malloc_zone_t *zone);
 222     /* Checks zone is well formed; if !zone, checks all zones */
 223
 224 extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);
 225     /* Prints summary on zone; if !zone, prints all zones */
 226
 227 extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats);
 228     /* Fills statistics for zone; if !zone, sums up all zones */
 229
 230 extern void malloc_zone_log(malloc_zone_t *zone, void *address);
 231     /* Controls logging of all activity; if !zone, for all zones;
 232     If address==0 nothing is logged;
 233     If address==-1 all activity is logged;
 234     Else only the activity regarding address is logged */
 235
 236 struct mstats {
 237     size_t      bytes_total;
 238     size_t      chunks_used;
 239     size_t      bytes_used;
 240     size_t      chunks_free;
 241     size_t      bytes_free;
 242 };
 243
 244 extern struct mstats mstats(void);
 245
 246 extern boolean_t malloc_zone_enable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 247 /* Increment the discharge checking enabled counter for a zone. Returns true if the zone supports checking, false if it does not. */
 248
 249 extern void malloc_zone_disable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 250 /* Decrement the discharge checking enabled counter for a zone. */
 251
 252 extern void malloc_zone_discharge(malloc_zone_t *zone, void *memory) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 253 /* Register memory that the programmer expects to be freed soon.
 254    zone may be NULL in which case the zone is determined using malloc_zone_from_ptr().
 255    If discharge checking is off for the zone this function is a no-op. */
 256
 257 #ifdef __BLOCKS__
 258 extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info)) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 259 /* Calls report_discharged for each block that was registered using malloc_zone_discharge() but has not yet been freed.
 260    info is used to provide zone defined information about the memory block.
 261    If zone is NULL then the enumeration covers all zones. */
 262 #else
 263 extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void *) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);
 264 #endif /* __BLOCKS__ */
 265
 266 __END_DECLS
 267
 268 #endif /* _MALLOC_MALLOC_H_ */