include/malloc/malloc.h

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef _MALLOC_MALLOC_H_
  27 #define _MALLOC_MALLOC_H_
  28
  29 #include <stddef.h>
  30 #include <mach/mach_types.h>
  31 #include <sys/cdefs.h>
  32
  33 __BEGIN_DECLS
  34 /*********      Type definitions        ************/
  35
  36 typedef struct _malloc_zone_t {
  37     /* Only zone implementors should depend on the layout of this structure;
  38     Regular callers should use the access functions below */
  39     void        *reserved1;     /* RESERVED FOR CFAllocator DO NOT USE */
  40     void        *reserved2;     /* RESERVED FOR CFAllocator DO NOT USE */
  41     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 */
  42     void        *(*malloc)(struct _malloc_zone_t *zone, size_t size);
  43     void        *(*calloc)(struct _malloc_zone_t *zone, size_t num_items, size_t size); /* same as malloc, but block returned is set to zero */
  44     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 */
  45     void        (*free)(struct _malloc_zone_t *zone, void *ptr);
  46     void        *(*realloc)(struct _malloc_zone_t *zone, void *ptr, size_t size);
  47     void        (*destroy)(struct _malloc_zone_t *zone); /* zone is destroyed and all memory reclaimed */
  48     const char  *zone_name;
  49
  50     /* Optional batch callbacks; these may be NULL */
  51     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) */
  52     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 */
  53
  54     struct malloc_introspection_t       *introspect;
  55     unsigned    version;
  56 } malloc_zone_t;
  57
  58 /*********      Creation and destruction        ************/
  59
  60 extern malloc_zone_t *malloc_default_zone(void);
  61     /* The initial zone */
  62
  63 extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags);
  64     /* Create a new zone */
  65
  66 extern void malloc_destroy_zone(malloc_zone_t *zone);
  67     /* Destroys zone and everything it allocated */
  68
  69 /*********      Block creation and manipulation ************/
  70
  71 extern void *malloc_zone_malloc(malloc_zone_t *zone, size_t size);
  72     /* Allocates a new pointer of size size; zone must be non-NULL */
  73
  74 extern void *malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size);
  75     /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */
  76
  77 extern void *malloc_zone_valloc(malloc_zone_t *zone, size_t size);
  78     /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */
  79
  80 extern void malloc_zone_free(malloc_zone_t *zone, void *ptr);
  81     /* Frees pointer in zone; zone must be non-NULL */
  82
  83 extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size);
  84     /* Enlarges block if necessary; zone must be non-NULL */
  85
  86 extern malloc_zone_t *malloc_zone_from_ptr(const void *ptr);
  87     /* Returns the zone for a pointer, or NULL if not in any zone.
  88     The ptr must have been returned from a malloc or realloc call. */
  89
  90 extern size_t malloc_size(const void *ptr);
  91     /* Returns size of given ptr */
  92
  93 /*********      Batch methods   ************/
  94
  95 extern unsigned malloc_zone_batch_malloc(malloc_zone_t *zone, size_t size, void **results, unsigned num_requested);
  96     /* Allocates num blocks of the same size; Returns the number truly allocated (may be 0) */
  97
  98 extern void malloc_zone_batch_free(malloc_zone_t *zone, void **to_be_freed, unsigned num);
  99     /* 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 */
 100
 101 /*********      Functions for zone implementors ************/
 102
 103 extern void malloc_zone_register(malloc_zone_t *zone);
 104     /* Registers a freshly created zone;
 105     Should typically be called after a zone has been created */
 106
 107 extern void malloc_zone_unregister(malloc_zone_t *zone);
 108     /* De-registers a zone
 109     Should typically be called before calling the zone destruction routine */
 110
 111 extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name);
 112     /* Sets the name of a zone */
 113
 114 extern const char *malloc_get_zone_name(malloc_zone_t *zone);
 115     /* Returns the name of a zone */
 116
 117 typedef struct {
 118     vm_address_t        address;
 119     vm_size_t           size;
 120 } vm_range_t;
 121
 122 typedef struct malloc_statistics_t {
 123     unsigned    blocks_in_use;
 124     size_t      size_in_use;
 125     size_t      max_size_in_use;        /* high water mark of touched memory */
 126     size_t      size_allocated;         /* reserved in memory */
 127 } malloc_statistics_t;
 128
 129 typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory);
 130     /* given a task, "reads" the memory at the given address and size
 131 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */
 132
 133 #define MALLOC_PTR_IN_USE_RANGE_TYPE    1       /* for allocated pointers */
 134 #define MALLOC_PTR_REGION_RANGE_TYPE    2       /* for region containing pointers */
 135 #define MALLOC_ADMIN_REGION_RANGE_TYPE  4       /* for region used internally */
 136
 137 typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);
 138     /* given a task and context, "records" the specified addresses */
 139
 140 typedef struct malloc_introspection_t {
 141     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 */
 142     size_t      (*good_size)(malloc_zone_t *zone, size_t size);
 143     boolean_t   (*check)(malloc_zone_t *zone); /* Consistency checker */
 144     void        (*print)(malloc_zone_t *zone, boolean_t verbose); /* Prints zone  */
 145     void        (*log)(malloc_zone_t *zone, void *address); /* Enables logging of activity */
 146     void        (*force_lock)(malloc_zone_t *zone); /* Forces locking zone */
 147     void        (*force_unlock)(malloc_zone_t *zone); /* Forces unlocking zone */
 148     void        (*statistics)(malloc_zone_t *zone, malloc_statistics_t *stats); /* Fills statistics */
 149 } malloc_introspection_t;
 150
 151 extern void malloc_printf(const char *format, ...);
 152     /* Convenience for logging errors and warnings;
 153     No allocation is performed during execution of this function;
 154     Only understands usual %p %d %s formats, and %y that expresses a number of bytes (5b,10KB,1MB...)
 155     */
 156
 157 /*********      Functions for performance tools ************/
 158
 159 extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count);
 160     /* Fills addresses and count with the addresses of the zones in task;
 161     Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */
 162
 163 /*********      Debug helpers   ************/
 164
 165 extern void malloc_zone_print_ptr_info(void *ptr);
 166     /* print to stdout if this pointer is in the malloc heap, free status, and size */
 167
 168 extern boolean_t malloc_zone_check(malloc_zone_t *zone);
 169     /* Checks zone is well formed; if !zone, checks all zones */
 170
 171 extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);
 172     /* Prints summary on zone; if !zone, prints all zones */
 173
 174 extern void malloc_zone_statistics(malloc_zone_t *zone, malloc_statistics_t *stats);
 175     /* Fills statistics for zone; if !zone, sums up all zones */
 176
 177 extern void malloc_zone_log(malloc_zone_t *zone, void *address);
 178     /* Controls logging of all activity; if !zone, for all zones;
 179     If address==0 nothing is logged;
 180     If address==-1 all activity is logged;
 181     Else only the activity regarding address is logged */
 182
 183 struct mstats {
 184     size_t      bytes_total;
 185     size_t      chunks_used;
 186     size_t      bytes_used;
 187     size_t      chunks_free;
 188     size_t      bytes_free;
 189 };
 190
 191 extern struct mstats mstats(void);
 192
 193 __END_DECLS
 194
 195 #endif /* _MALLOC_MALLOC_H_ */