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