chiark - git - mdw - mLib/blob - track.h

   1 /* -*-c-*-
   2  *
   3  * $Id: track.h,v 1.6 2004/04/08 01:36:13 mdw Exp $
   4  *
   5  * Tracing functions for debugging
   6  *
   7  * (c) 1998 Straylight/Edgeware
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of the mLib utilities library.
  13  *
  14  * mLib is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU Library General Public License as
  16  * published by the Free Software Foundation; either version 2 of the
  17  * License, or (at your option) any later version.
  18  *
  19  * mLib is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU Library General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU Library General Public
  25  * License along with mLib; if not, write to the Free
  26  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  27  * MA 02111-1307, USA.
  28  */
  29
  30 #ifndef MLIB_TRACK_H
  31 #define MLIB_TRACK_H
  32
  33 #ifdef __cplusplus
  34   extern "C" {
  35 #endif
  36
  37 #include <stdlib.h>
  38
  39 /*----- Options and conventions -------------------------------------------*
  40  *
  41  * The following macros affect the tracking system:
  42  *
  43  * @TRACK_ENABLE@:      Enable tracking of memory allocations
  44  * @TRACK_BLAME@:       Register my context blocks in allocations
  45  *
  46  * The reason there are two switches is simple.  It's often the case that a
  47  * library routine allocates memory for its client.  Therefore, whether we
  48  * want to record the library or the client depends on how much we trust
  49  * the two pieces of software.  Setting @TRACK_ENABLE@ and @TRACK_BLAME@
  50  * suggests that the current source file might leak memory, so we want its
  51  * context markers in the list.  Setting @TRACK_ENABLE@ but not
  52  * @TRACK_BLAME@ suggests that we trust this code, but not the code which
  53  * calls it, so we want to preserve the caller's context markers.
  54  *
  55  * Got it?  Good.
  56  */
  57
  58 /*----- Type definitions --------------------------------------------------*/
  59
  60 /* --- A context buffer --- */
  61
  62 typedef struct track_ctx {
  63   struct track_ctx *next;
  64   const char *s;
  65 } track_ctx;
  66
  67 /*----- Functions provided ------------------------------------------------*/
  68
  69 /* --- @track_level@ --- *
  70  *
  71  * Arguments:   @unsigned int l@ = tracing level for allocation messages
  72  *
  73  * Returns:     ---
  74  *
  75  * Use:         Sets the trace level for allocation messages.
  76  */
  77
  78 extern void track_level(unsigned int /*l*/);
  79
  80 /* --- @track_push@ --- *
  81  *
  82  * Arguments:   @track_ctx *ctx@ = context holder to push
  83  *
  84  * Returns:     ---
  85  *
  86  * Use:         Pushes the given context block onto the stack.
  87  */
  88
  89 extern void track_push(track_ctx */*ctx*/);
  90
  91 /* --- @track_pop@ --- *
  92  *
  93  * Arguments:   @track_ctx *ctx@ = context holder to pop
  94  *
  95  * Returns:     ---
  96  *
  97  * Use:         Removes the given context block from the stack.
  98  */
  99
 100 extern void track_pop(track_ctx */*ctx*/);
 101
 102 /* --- @track_malloc@ --- *
 103  *
 104  * Arguments:   @size_t sz@ = size requested
 105  *
 106  * Returns:     Pointer to allocated space, or null
 107  *
 108  * Use:         Allocates memory, and tracks how much is allocated.
 109  */
 110
 111 extern void *track_malloc(size_t /*sz*/);
 112
 113 /* --- @track_free@ --- *
 114  *
 115  * Arguments:   @void *p@ = pointer to an allocated block
 116  *
 117  * Returns:     ---
 118  *
 119  * Use:         Frees memory, and tracks how much is still allocated.
 120  */
 121
 122 extern void track_free(void */*p*/);
 123
 124 /* --- @track_realloc@ --- *
 125  *
 126  * Arguments:   @void *p@ = pointer to an allocated block
 127  *              @size_t sz@ = how big it wants to be
 128  *
 129  * Returns:     Pointer to the new block.
 130  *
 131  * Use:         Reallocates a block, tracking how much memory is still
 132  *              available.
 133  */
 134
 135 extern void *track_realloc(void */*p*/, size_t /*sz*/);
 136
 137 /* --- @track_used@ --- *
 138  *
 139  * Arguments:   ---
 140  *
 141  * Returns:     A count of how much memory is used currently.
 142  *
 143  * Use:         Returns the amount of memory which the @track_@-functions
 144  *              above have counted as being currently allocated.
 145  */
 146
 147 extern unsigned long track_used(void);
 148
 149 /* --- @track_list@ --- *
 150  *
 151  * Arguments:   @unsigned int l@ = trace level to use
 152  *
 153  * Returns:     ---
 154  *
 155  * Use:         Traces a dump of the currently known blocks.  Combined with
 156  *              a verbose dump of allocations and deallocations, and a
 157  *              good idea of which blocks were allocated where, this can
 158  *              be useful for locating memory leaks.  It's not exactly a
 159  *              picnic, though.
 160  */
 161
 162 extern void track_list(unsigned int l);
 163
 164 /*----- Macro wrappers ----------------------------------------------------*/
 165
 166 /* --- If tracking is to be done, set it up --- */
 167
 168 #ifdef TRACK_ENABLE
 169 #  undef malloc
 170 #  define malloc(sz) track_malloc(sz)
 171 #  undef free
 172 #  define free(p) track_free(p)
 173 #  undef realloc
 174 #  define realloc(p, sz) track_realloc(p, sz)
 175 #endif
 176
 177 /* --- Provide a context for doing track-related things --- */
 178
 179 #ifdef TRACK_ENABLE
 180 #  define TRACK(x) x
 181 #else
 182 #  define TRACK(x)
 183 #endif
 184
 185 /* --- Handle contexts --- */
 186
 187 #if defined(TRACK_ENABLE) && defined(TRACK_BLAME)
 188 #  define TRACK_NCTX(name, string) track_ctx name = { 0, string }
 189 #  define TRACK_NPUSH(name) track_push(name)
 190 #  define TRACK_NPOP(name) track_pop(name)
 191 #  define TRACK_CTX(string) TRACK_NCTX(__track_ctx, string)
 192 #  define TRACK_PUSH TRACK_NPUSH(__track_ctx)
 193 #  define TRACK_POP TRACK_NPOP(__track_ctx)
 194 #else
 195 #  define TRACK_NCTX(name, string)
 196 #  define TRACK_NPUSH(name) ((void)0)
 197 #  define TRACK_NPOP(name) ((void)0)
 198 #  define TRACK_CTX(string)
 199 #  define TRACK_PUSH ((void)0)
 200 #  define TRACK_POP ((void)0)
 201 #endif
 202
 203 /*----- That's all, folks -------------------------------------------------*/
 204
 205 #ifdef __cplusplus
 206   }
 207 #endif
 208
 209 #endif