| 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);␊ |
| 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 | extern void * malloc_zone_posix_memalign(malloc_zone_t *zone, size_t alignment, size_t size);␊ |
| 112 | ␊ |
| 113 | /*********␉Batch methods␉************/␊ |
| 114 | ␊ |
| 115 | extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void **results, unsigned num_requested);␊ |
| 116 | /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */␊ |
| 117 | ␊ |
| 118 | extern void malloc_zone_batch_free(malloc_zone_t *zone, void **to_be_freed, unsigned num);␊ |
| 119 | /* 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 */␊ |
| 120 | ␊ |
| 121 | /*********␉Functions for libcache␉************/␊ |
| 122 | ␊ |
| 123 | extern malloc_zone_t *malloc_default_purgeable_zone(void) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);␊ |
| 124 | /* Returns a pointer to the default purgeable_zone. */␊ |
| 125 | ␊ |
| 126 | extern void malloc_make_purgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);␊ |
| 127 | /* Make an allocation from the purgeable zone purgeable if possible. */␊ |
| 128 | ␊ |
| 129 | extern int malloc_make_nonpurgeable(void *ptr) __OSX_AVAILABLE_STARTING(__MAC_10_6, __IPHONE_3_0);␊ |
| 130 | /* Makes an allocation from the purgeable zone nonpurgeable.␊ |
| 131 | * Returns zero if the contents were not purged since the last␊ |
| 132 | * call to malloc_make_purgeable, else returns non-zero. */␊ |
| 133 | ␊ |
| 134 | /*********␉Functions for zone implementors␉************/␊ |
| 135 | ␊ |
| 136 | extern void malloc_zone_register(malloc_zone_t *zone);␊ |
| 137 | /* Registers a custom malloc zone; Should typically be called after a ␊ |
| 138 | * malloc_zone_t has been filled in with custom methods by a client. See␊ |
| 139 | * malloc_create_zone for creating additional malloc zones with the␊ |
| 140 | * default allocation and free behavior. */␊ |
| 141 | ␊ |
| 142 | extern void malloc_zone_unregister(malloc_zone_t *zone);␊ |
| 143 | /* De-registers a zone␊ |
| 144 | Should typically be called before calling the zone destruction routine */␊ |
| 145 | ␊ |
| 146 | extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name);␊ |
| 147 | /* Sets the name of a zone */␊ |
| 148 | ␊ |
| 149 | extern const char *malloc_get_zone_name(malloc_zone_t *zone);␊ |
| 150 | /* Returns the name of a zone */␊ |
| 151 | ␊ |
| 152 | size_t malloc_zone_pressure_relief(malloc_zone_t *zone, size_t goal) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);␊ |
| 153 | /* malloc_zone_pressure_relief() advises the malloc subsystem that the process is under memory pressure and ␊ |
| 154 | * that the subsystem should make its best effort towards releasing (i.e. munmap()-ing) "goal" bytes from "zone". ␊ |
| 155 | * If "goal" is passed as zero, the malloc subsystem will attempt to achieve maximal pressure relief in "zone". ␊ |
| 156 | * If "zone" is passed as NULL, all zones are examined for pressure relief opportunities. ␊ |
| 157 | * malloc_zone_pressure_relief() returns the number of bytes released. ␊ |
| 158 | */␊ |
| 159 | ␊ |
| 160 | typedef struct {␊ |
| 161 | vm_address_t␉address;␊ |
| 162 | vm_size_t␉␉size;␊ |
| 163 | } vm_range_t;␊ |
| 164 | ␊ |
| 165 | typedef struct malloc_statistics_t {␊ |
| 166 | unsigned␉blocks_in_use;␊ |
| 167 | size_t␉size_in_use;␊ |
| 168 | size_t␉max_size_in_use;␉/* high water mark of touched memory */␊ |
| 169 | size_t␉size_allocated;␉␉/* reserved in memory */␊ |
| 170 | } malloc_statistics_t;␊ |
| 171 | ␊ |
| 172 | typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory);␊ |
| 173 | /* given a task, "reads" the memory at the given address and size␊ |
| 174 | local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */␊ |
| 175 | ␊ |
| 176 | #define MALLOC_PTR_IN_USE_RANGE_TYPE␉1␉/* for allocated pointers */␊ |
| 177 | #define MALLOC_PTR_REGION_RANGE_TYPE␉2␉/* for region containing pointers */␊ |
| 178 | #define MALLOC_ADMIN_REGION_RANGE_TYPE␉4␉/* for region used internally */␊ |
| 179 | #define MALLOC_ZONE_SPECIFIC_FLAGS␉0xff00␉/* bits reserved for zone-specific purposes */␊ |
| 180 | ␊ |
| 181 | typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);␊ |
| 182 | /* given a task and context, "records" the specified addresses */␊ |
| 183 | ␊ |
| 184 | typedef struct malloc_introspection_t {␊ |
| 185 | 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 */␊ |
| 186 | size_t␉(*good_size)(malloc_zone_t *zone, size_t size);␊ |
| 187 | boolean_t ␉(*check)(malloc_zone_t *zone); /* Consistency checker */␊ |
| 188 | void ␉(*print)(malloc_zone_t *zone, boolean_t verbose); /* Prints zone */␊ |
| 189 | void␉(*log)(malloc_zone_t *zone, void *address); /* Enables logging of activity */␊ |
| 190 | void␉(*force_lock)(malloc_zone_t *zone); /* Forces locking zone */␊ |
| 191 | void␉(*force_unlock)(malloc_zone_t *zone); /* Forces unlocking zone */␊ |
| 192 | void␉(*statistics)(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */␊ |
| 193 | boolean_t (*zone_locked)(malloc_zone_t *zone); /* Are any zone locks held */␊ |
| 194 | ␊ |
| 195 | /* Discharge checking. Present in version >= 7. */␊ |
| 196 | boolean_t␉(*enable_discharge_checking)(malloc_zone_t *zone);␊ |
| 197 | void␉(*disable_discharge_checking)(malloc_zone_t *zone);␊ |
| 198 | void␉(*discharge)(malloc_zone_t *zone, void *memory);␊ |
| 199 | #ifdef __BLOCKS__␊ |
| 200 | void (*enumerate_discharged_pointers)(malloc_zone_t *zone, void (^report_discharged)(void *memory, void *info));␊ |
| 201 | #else␊ |
| 202 | void␉*enumerate_unavailable_without_blocks; ␊ |
| 203 | #endif /* __BLOCKS__ */␊ |
| 204 | } malloc_introspection_t;␊ |
| 205 | ␊ |
| 206 | extern void malloc_printf(const char *format, ...);␊ |
| 207 | /* Convenience for logging errors and warnings;␊ |
| 208 | No allocation is performed during execution of this function;␊ |
| 209 | Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...)␊ |
| 210 | */␊ |
| 211 | ␊ |
| 212 | /*********␉Functions for performance tools␉************/␊ |
| 213 | ␊ |
| 214 | extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count);␊ |
| 215 | /* Fills addresses and count with the addresses of the zones in task;␊ |
| 216 | Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */␊ |
| 217 | ␊ |
| 218 | /*********␉Debug helpers␉************/␊ |
| 219 | ␊ |
| 220 | extern void malloc_zone_print_ptr_info(void *ptr);␊ |
| 221 | /* print to stdout if this pointer is in the malloc heap, free status, and size */␊ |
| 222 | ␊ |
| 223 | extern boolean_t malloc_zone_check(malloc_zone_t *zone);␊ |
| 224 | /* Checks zone is well formed; if !zone, checks all zones */␊ |
| 225 | ␊ |
| 226 | extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);␊ |
| 227 | /* Prints summary on zone; if !zone, prints all zones */␊ |
| 228 | ␊ |
| 229 | extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats);␊ |
| 230 | /* Fills statistics for zone; if !zone, sums up all zones */␊ |
| 231 | ␊ |
| 232 | extern void malloc_zone_log(malloc_zone_t *zone, void *address);␊ |
| 233 | /* Controls logging of all activity; if !zone, for all zones;␊ |
| 234 | If address==0 nothing is logged;␊ |
| 235 | If address==-1 all activity is logged;␊ |
| 236 | Else only the activity regarding address is logged */␊ |
| 237 | ␊ |
| 238 | struct mstats {␊ |
| 239 | size_t␉bytes_total;␊ |
| 240 | size_t␉chunks_used;␊ |
| 241 | size_t␉bytes_used;␊ |
| 242 | size_t␉chunks_free;␊ |
| 243 | size_t␉bytes_free;␊ |
| 244 | };␊ |
| 245 | ␊ |
| 246 | extern struct mstats mstats(void);␊ |
| 247 | ␊ |
| 248 | extern boolean_t malloc_zone_enable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);␊ |
| 249 | /* Increment the discharge checking enabled counter for a zone. Returns true if the zone supports checking, false if it does not. */␊ |
| 250 | ␊ |
| 251 | extern void malloc_zone_disable_discharge_checking(malloc_zone_t *zone) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);␊ |
| 252 | /* Decrement the discharge checking enabled counter for a zone. */␊ |
| 253 | ␊ |
| 254 | extern void malloc_zone_discharge(malloc_zone_t *zone, void *memory) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);␊ |
| 255 | /* Register memory that the programmer expects to be freed soon. ␊ |
| 256 | zone may be NULL in which case the zone is determined using malloc_zone_from_ptr(). ␊ |
| 257 | If discharge checking is off for the zone this function is a no-op. */␊ |
| 258 | ␊ |
| 259 | #ifdef __BLOCKS__␊ |
| 260 | 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);␊ |
| 261 | /* Calls report_discharged for each block that was registered using malloc_zone_discharge() but has not yet been freed. ␊ |
| 262 | info is used to provide zone defined information about the memory block. ␊ |
| 263 | If zone is NULL then the enumeration covers all zones. */␊ |
| 264 | #else␊ |
| 265 | extern void malloc_zone_enumerate_discharged_pointers(malloc_zone_t *zone, void *) __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_4_3);␊ |
| 266 | #endif /* __BLOCKS__ */␊ |
| 267 | ␊ |
| 268 | __END_DECLS␊ |
| 269 | ␊ |
| 270 | #endif /* _MALLOC_MALLOC_H_ */␊ |
| 271 | |
