gen.subproj/malloc.h

   1 /*
   2  * Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22
  23 #import <stddef.h>
  24 #import <mach/mach.h>
  25
  26 /*********      Type definitions        ************/
  27
  28 typedef struct _malloc_zone_t {
  29     /* Only zone implementors should depend on the layout of this structure;
  30     Regular callers should use the access functions below */
  31     void        *reserved1;
  32     void        *reserved2;
  33     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 */
  34     void *(*malloc)(struct _malloc_zone_t *zone, size_t size);
  35     void *(*calloc)(struct _malloc_zone_t *zone, size_t num_items, size_t size); /* same as malloc, but block returned is set to zero */
  36     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 */
  37     void (*free)(struct _malloc_zone_t *zone, void *ptr);
  38     void *(*realloc)(struct _malloc_zone_t *zone, void *ptr, size_t size);
  39     void (*destroy)(struct _malloc_zone_t *zone); /* zone is destroyed and all memory reclaimed */
  40     const char  *zone_name;
  41     void        *reserved3;
  42     void        *reserved4;
  43     struct malloc_introspection_t       *introspect;
  44     void        *reserved5;
  45 } malloc_zone_t;
  46
  47 /*********      Creation and destruction        ************/
  48
  49 extern malloc_zone_t *malloc_default_zone(void);
  50     /* The initial zone */
  51
  52 extern malloc_zone_t *malloc_create_zone(vm_size_t start_size, unsigned flags);
  53     /* Create a new zone */
  54
  55 extern void malloc_destroy_zone(malloc_zone_t *zone);
  56     /* Destroys zone and everything it allocated */
  57
  58 /*********      Block creation and manipulation ************/
  59
  60 extern void *malloc_zone_malloc(malloc_zone_t *zone, size_t size);
  61     /* Allocates a new pointer of size size; zone must be non-NULL */
  62
  63 extern void *malloc_zone_calloc(malloc_zone_t *zone, size_t num_items, size_t size);
  64     /* Allocates a new pointer of size num_items * size; block is cleared; zone must be non-NULL */
  65
  66 extern void *malloc_zone_valloc(malloc_zone_t *zone, size_t size);
  67     /* Allocates a new pointer of size size; zone must be non-NULL; Pointer is guaranteed to be page-aligned and block is cleared */
  68
  69 extern void malloc_zone_free(malloc_zone_t *zone, void *ptr);
  70     /* Frees pointer in zone; zone must be non-NULL */
  71
  72 extern void *malloc_zone_realloc(malloc_zone_t *zone, void *ptr, size_t size);
  73     /* Enlarges block if necessary; zone must be non-NULL */
  74
  75 extern malloc_zone_t *malloc_zone_from_ptr(const void *ptr);
  76     /* Returns the zone for a pointer, or NULL if not in any zone.
  77     The ptr must have been returned from a malloc or realloc call. */
  78
  79 extern size_t malloc_size(const void *ptr);
  80     /* Returns size of given ptr */
  81
  82 /*********      Functions for zone implementors ************/
  83
  84 extern void malloc_zone_register(malloc_zone_t *zone);
  85     /* Registers a freshly created zone;
  86     Should typically be called after a zone has been created */
  87
  88 extern void malloc_zone_unregister(malloc_zone_t *zone);
  89     /* De-registers a zone
  90     Should typically be called before calling the zone destruction routine */
  91
  92 extern void malloc_set_zone_name(malloc_zone_t *zone, const char *name);
  93     /* Sets the name of a zone */
  94
  95 extern const char *malloc_get_zone_name(malloc_zone_t *zone);
  96     /* Returns the name of a zone */
  97
  98 typedef struct {
  99     vm_address_t        address;
 100     vm_size_t           size;
 101 } vm_range_t;
 102
 103 typedef kern_return_t memory_reader_t(task_t remote_task, vm_address_t remote_address, vm_size_t size, void **local_memory);
 104     /* given a task, "reads" the memory at the given address and size
 105 local_memory: set to a contiguous chunk of memory; validity of local_memory is assumed to be limited (until next call) */
 106
 107 #define MALLOC_PTR_IN_USE_RANGE_TYPE    1       /* for allocated pointers */
 108 #define MALLOC_PTR_REGION_RANGE_TYPE    2       /* for region containing pointers */
 109 #define MALLOC_ADMIN_REGION_RANGE_TYPE  4       /* for region used internally */
 110
 111 typedef void vm_range_recorder_t(task_t, void *, unsigned type, vm_range_t *, unsigned);
 112     /* given a task and context, "records" the specified addresses */
 113
 114 typedef struct malloc_introspection_t {
 115     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 */
 116     size_t      (*good_size)(malloc_zone_t *zone, size_t size);
 117     boolean_t   (*check)(malloc_zone_t *zone); /* Consistency checker */
 118     void        (*print)(malloc_zone_t *zone, boolean_t verbose); /* Prints zone  */
 119     void        (*log)(malloc_zone_t *zone, void *address); /* Enables logging of activity */
 120     void        (*force_lock)(malloc_zone_t *zone); /* Forces locking zone */
 121     void        (*force_unlock)(malloc_zone_t *zone); /* Forces unlocking zone */
 122 } malloc_introspection_t;
 123
 124 extern void malloc_printf(const char *format, ...);
 125     /* Convenience for logging errors and warnings;
 126     No allocation is performed during execution of this function;
 127     Only understand %p %d %x %s formats
 128     */
 129
 130 /*********      Functions for performance tools ************/
 131
 132 extern kern_return_t malloc_get_all_zones(task_t task, memory_reader_t reader, vm_address_t **addresses, unsigned *count);
 133     /* Fills addresses and count with the addresses of the zones in task;
 134     Note that the validity of the addresses returned correspond to the validity of the memory returned by reader */
 135
 136 /*********      Debug helpers   ************/
 137
 138 extern void malloc_zone_print_ptr_info(void *ptr);
 139     /* print to stdout if this pointer is in the malloc heap, free status, and size */
 140
 141 extern boolean_t malloc_zone_check(malloc_zone_t *zone);
 142     /* Checks zone is well formed; if !zone, checks all zones */
 143
 144 extern void malloc_zone_print(malloc_zone_t *zone, boolean_t verbose);
 145     /* Prints summary on zone; if !zone, prints all zones */
 146
 147 extern void malloc_zone_log(malloc_zone_t *zone, void *address);
 148     /* Controls logging of all activity; if !zone, for all zones;
 149     If address==0 nothing is logged;
 150     If address==-1 all activity is logged;
 151     Else only the activity regarding address is logged */