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
  31 __BEGIN_DECLS
  32 /*********      Type definitions        ************/
  33
  34 typedef struct _malloc_zone_t {
  35     /* Only zone implementors should depend on the layout of this structure;
  36     Regular callers should use the access functions below */
  37     unsigned    version;
  38     void        *reserved2;
  39     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 */
  40     void        *(*malloc)(struct _malloc_zone_t *zone, size_t size);
  41     void        *(*calloc)(struct _malloc_zone_t *zone, size_t num_items, size_t size); /* same as malloc, but block returned is set to zero */
  42     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 */
  43     void        (*free)(struct _malloc_zone_t *zone, void *ptr);
  44     void        *(*realloc)(struct _malloc_zone_t *zone, void *ptr, size_t size);
  45     void        (*destroy)(struct _malloc_zone_t *zone); /* zone is destroyed and all memory reclaimed */
  46     const char  *zone_name;
  47
  48     /* Optional batch callbacks; these may be NULL */
  49     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) */
  50     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 */
  51
  52     struct malloc_introspection_t       *introspect;
  53     void        *reserved5;
  54 } malloc_zone_t;
  55
  56 /*********      Creation and destruction        ************/
  57
  58 extern malloc_zone_t *malloc_default_zone(void);
  59     /* The initial zone */
  60
  61 extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags);
  62     /* Create a new zone */
  63
  64 extern void malloc_destroy_zone(malloc_zone_t *zone);
  65     /* Destroys zone and everything it allocated */
  66
  67 /*********      Block creation and manipulation ************/
  68
  69 extern void *malloc_zone_malloc(malloc_zone_t *zone, size_t size);
  70     /* Allocates a new pointer of size size; zone must be non-NULL */
  71
  72 extern void *malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size);
  73     /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */
  74
  75 extern void *malloc_zone_valloc(malloc_zone_t *zone, size_t size);
  76     /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */
  77
  78 extern void malloc_zone_free(malloc_zone_t *zone, void *ptr);
  79     /* Frees pointer in zone; zone must be non-NULL */
  80
  81 extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size);
  82     /* Enlarges block if necessary; zone must be non-NULL */
  83
  84 extern malloc_zone_t *malloc_zone_from_ptr(const void *ptr);
  85     /* Returns the zone for a pointer, or NULL if not in any zone.
  86     The ptr must have been returned from a malloc or realloc call. */
  87
  88 extern size_t malloc_size(const void *ptr);
  89     /* Returns size of given ptr */
  90
  91 /*********      Batch methods   ************/
  92
  93 extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void **results, unsigned num_requested);
  94     /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */
  95
  96 extern void malloc_zone_batch_free(malloc_zone_t *zone, void **to_be_freed, unsigned num);
  97     /* 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 */
  98
  99 /*********      Functions for zone implementors ************/
 100
 101 extern void malloc_zone_register(malloc_zone_t *zone);
 102     /* Registers a freshly created zone;
 103     Should typically be called after a zone has been created */
 104
 105 extern void malloc_zone_unregister(malloc_zone_t *zone);
 106     /* De-registers a zone
 107     Should typically be called before calling the zone destruction routine */
 108
 109 extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name);
 110     /* Sets the name of a zone */
 111
 112 extern const char *malloc_get_zone_name(malloc_zone_t *zone);
 113     /* Returns the name of a zone */
 114
 115 typedef struct {
 116     vm_address_t        address;
 117     vm_size_t           size;
 118 } vm_range_t;
 119
 120 typedef struct malloc_statistics_t {
 121     unsigned    blocks_in_use;
 122     size_t      size_in_use;
 123     size_t      max_size_in_use;        /* high water mark of touched memory */
 124     size_t      size_allocated;         /* reserved in memory */
 125 } malloc_statistics_t;
 126
 127 typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory);
 128     /* given a task, "reads" the memory at the given address and size
 129 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */
 130
 131 #define MALLOC_PTR_IN_USE_RANGE_TYPE    1       /* for allocated pointers */
 132 #define MALLOC_PTR_REGION_RANGE_TYPE    2       /* for region containing pointers */
 133 #define MALLOC_ADMIN_REGION_RANGE_TYPE  4       /* for region used internally */
 134
 135 typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);
 136     /* given a task and context, "records" the specified addresses */
 137
 138 typedef struct malloc_introspection_t {
 139     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 */
 140     size_t      (*good_size)(malloc_zone_t *zone, size_t size);
 141     boolean_t   (*check)(malloc_zone_t *zone); /* Consistency checker */
 142     void        (*print)(malloc_zone_t *zone, boolean_t verbose); /* Prints zone  */
 143     void        (*log)(malloc_zone_t *zone, void *address); /* Enables logging of activity */
 144     void        (*force_lock)(malloc_zone_t *zone); /* Forces locking zone */
 145     void        (*force_unlock)(malloc_zone_t *zone); /* Forces unlocking zone */
 146     void        (*statistics)(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */
 147 } malloc_introspection_t;
 148
 149 extern void malloc_printf(const char *format, ...);
 150     /* Convenience for logging errors and warnings;
 151     No allocation is performed during execution of this function;
 152     Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...)
 153     */
 154
 155 /*********      Functions for performance tools ************/
 156
 157 extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count);
 158     /* Fills addresses and count with the addresses of the zones in task;
 159     Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */
 160
 161 /*********      Debug helpers   ************/
 162
 163 extern void malloc_zone_print_ptr_info(void *ptr);
 164     /* print to stdout if this pointer is in the malloc heap, free status, and size */
 165
 166 extern boolean_t malloc_zone_check(malloc_zone_t *zone);
 167     /* Checks zone is well formed; if !zone, checks all zones */
 168
 169 extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);
 170     /* Prints summary on zone; if !zone, prints all zones */
 171
 172 extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats);
 173     /* Fills statistics for zone; if !zone, sums up all zones */
 174
 175 extern void malloc_zone_log(malloc_zone_t *zone, void *address);
 176     /* Controls logging of all activity; if !zone, for all zones;
 177     If address==0 nothing is logged;
 178     If address==-1 all activity is logged;
 179     Else only the activity regarding address is logged */
 180 __END_DECLS
 181
 182 #endif /* _MALLOC_MALLOC_H_ */