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 35typedef 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 68extern malloc_zone_t *malloc_default_zone(void); 69 /* The initial zone */ 70 71extern 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 74extern void malloc_destroy_zone(malloc_zone_t *zone); 75 /* Destroys zone and everything it allocated */ 76 77/********* Block creation and manipulation ************/ 78 79extern 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 82extern 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 85extern 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 88extern void malloc_zone_free(malloc_zone_t *zone, void *ptr); 89 /* Frees pointer in zone; zone must be non-NULL */ 90 91extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size); 92 /* Enlarges block if necessary; zone must be non-NULL */ 93 94extern 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 98extern size_t malloc_size(const void *ptr); 99 /* Returns size of given ptr */ 100 101extern 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 104extern 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 113extern 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 116extern 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 121extern 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 124extern 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 127extern 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 134extern 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 140extern 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 144extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name); 145 /* Sets the name of a zone */ 146 147extern const char *malloc_get_zone_name(malloc_zone_t *zone); 148 /* Returns the name of a zone */ 149 150size_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 158typedef struct { 159 vm_address_t address; 160 vm_size_t size; 161} vm_range_t; 162 163typedef 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 170typedef 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 172local_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 179typedef 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 182typedef 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 204extern 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 212extern 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 218extern 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 221extern boolean_t malloc_zone_check(malloc_zone_t *zone); 222 /* Checks zone is well formed; if !zone, checks all zones */ 223 224extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose); 225 /* Prints summary on zone; if !zone, prints all zones */ 226 227extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats); 228 /* Fills statistics for zone; if !zone, sums up all zones */ 229 230extern 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 236struct 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 244extern struct mstats mstats(void); 245 246extern 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 249extern 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 252extern 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__ 258extern 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 263extern 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_ */ 269