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

   1 /* -*-c-*-
   2  *
   3  * $Id: track.h,v 1.4 1999/10/22 22:40:25 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: track.h,v $
  33  * Revision 1.4  1999/10/22 22:40:25  mdw
  34  * Change naming slightly.  Still not documented, though.
  35  *
  36  * Revision 1.3  1999/05/06 19:51:36  mdw
  37  * Reformatted the LGPL notice a little bit.
  38  *
  39  * Revision 1.2  1999/05/05 18:50:31  mdw
  40  * Change licensing conditions to LGPL.
  41  *
  42  * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
  43  * Initial version of mLib
  44  *
  45  */
  46
  47 #ifndef TRACK_H
  48 #define TRACK_H
  49
  50 #ifdef __cplusplus
  51   extern "C" {
  52 #endif
  53
  54 #include <stdlib.h>
  55
  56 /*----- Options and conventions -------------------------------------------*
  57  *
  58  * The following macros affect the tracking system:
  59  *
  60  * @TRACK_ENABLE@:      Enable tracking of memory allocations
  61  * @TRACK_BLAME@:       Register my context blocks in allocations
  62  *
  63  * The reason there are two switches is simple.  It's often the case that a
  64  * library routine allocates memory for its client.  Therefore, whether we
  65  * want to record the library or the client depends on how much we trust
  66  * the two pieces of software.  Setting @TRACK_ENABLE@ and @TRACK_BLAME@
  67  * suggests that the current source file might leak memory, so we want its
  68  * context markers in the list.  Setting @TRACK_ENABLE@ but not
  69  * @TRACK_BLAME@ suggests that we trust this code, but not the code which
  70  * calls it, so we want to preserve the caller's context markers.
  71  *
  72  * Got it?  Good.
  73  */
  74
  75 /*----- Type definitions --------------------------------------------------*/
  76
  77 /* --- A context buffer --- */
  78
  79 typedef struct track_ctx {
  80   struct track_ctx *next;
  81   const char *s;
  82 } track_ctx;
  83
  84 /*----- Functions provided ------------------------------------------------*/
  85
  86 /* --- @track_level@ --- *
  87  *
  88  * Arguments:   @unsigned int l@ = tracing level for allocation messages
  89  *
  90  * Returns:     ---
  91  *
  92  * Use:         Sets the trace level for allocation messages.
  93  */
  94
  95 extern void track_level(unsigned int /*l*/);
  96
  97 /* --- @track_push@ --- *
  98  *
  99  * Arguments:   @track_ctx *ctx@ = context holder to push
 100  *
 101  * Returns:     ---
 102  *
 103  * Use:         Pushes the given context block onto the stack.
 104  */
 105
 106 extern void track_push(track_ctx */*ctx*/);
 107
 108 /* --- @track_pop@ --- *
 109  *
 110  * Arguments:   @track_ctx *ctx@ = context holder to pop
 111  *
 112  * Returns:     ---
 113  *
 114  * Use:         Removes the given context block from the stack.
 115  */
 116
 117 extern void track_pop(track_ctx */*ctx*/);
 118
 119 /* --- @track_malloc@ --- *
 120  *
 121  * Arguments:   @size_t sz@ = size requested
 122  *
 123  * Returns:     Pointer to allocated space, or null
 124  *
 125  * Use:         Allocates memory, and tracks how much is allocated.
 126  */
 127
 128 extern void *track_malloc(size_t /*sz*/);
 129
 130 /* --- @track_free@ --- *
 131  *
 132  * Arguments:   @void *p@ = pointer to an allocated block
 133  *
 134  * Returns:     ---
 135  *
 136  * Use:         Frees memory, and tracks how much is still allocated.
 137  */
 138
 139 extern void track_free(void */*p*/);
 140
 141 /* --- @track_realloc@ --- *
 142  *
 143  * Arguments:   @void *p@ = pointer to an allocated block
 144  *              @size_t sz@ = how big it wants to be
 145  *
 146  * Returns:     Pointer to the new block.
 147  *
 148  * Use:         Reallocates a block, tracking how much memory is still
 149  *              available.
 150  */
 151
 152 extern void *track_realloc(void */*p*/, size_t /*sz*/);
 153
 154 /* --- @track_used@ --- *
 155  *
 156  * Arguments:   ---
 157  *
 158  * Returns:     A count of how much memory is used currently.
 159  *
 160  * Use:         Returns the amount of memory which the @track_@-functions
 161  *              above have counted as being currently allocated.
 162  */
 163
 164 extern unsigned long track_used(void);
 165
 166 /* --- @track_list@ --- *
 167  *
 168  * Arguments:   @unsigned int l@ = trace level to use
 169  *
 170  * Returns:     ---
 171  *
 172  * Use:         Traces a dump of the currently known blocks.  Combined with
 173  *              a verbose dump of allocations and deallocations, and a
 174  *              good idea of which blocks were allocated where, this can
 175  *              be useful for locating memory leaks.  It's not exactly a
 176  *              picnic, though.
 177  */
 178
 179 extern void track_list(unsigned int l);
 180
 181 /*----- Macro wrappers ----------------------------------------------------*/
 182
 183 /* --- If tracking is to be done, set it up --- */
 184
 185 #ifdef TRACK_ENABLE
 186 #  undef malloc
 187 #  define malloc(sz) track_malloc(sz)
 188 #  undef free
 189 #  define free(p) track_free(p)
 190 #  undef realloc
 191 #  define realloc(p, sz) track_realloc(p, sz)
 192 #endif
 193
 194 /* --- Provide a context for doing track-related things --- */
 195
 196 #ifdef TRACK_ENABLE
 197 #  define TRACK(x) x
 198 #else
 199 #  define TRACK(x)
 200 #endif
 201
 202 /* --- Handle contexts --- */
 203
 204 #if defined(TRACK_ENABLE) && defined(TRACK_BLAME)
 205 #  define TRACK_NCTX(name, string) track_ctx name = { 0, string }
 206 #  define TRACK_NPUSH(name) track_push(name)
 207 #  define TRACK_NPOP(name) track_pop(name)
 208 #  define TRACK_CTX(string) TRACK_NCTX(__track_ctx, string)
 209 #  define TRACK_PUSH TRACK_NPUSH(__track_ctx)
 210 #  define TRACK_POP TRACK_NPOP(__track_ctx)
 211 #else
 212 #  define TRACK_NCTX(name, string)
 213 #  define TRACK_NPUSH(name) ((void)0)
 214 #  define TRACK_NPOP(name) ((void)0)
 215 #  define TRACK_CTX(string)
 216 #  define TRACK_PUSH ((void)0)
 217 #  define TRACK_POP ((void)0)
 218 #endif
 219
 220 /*----- That's all, folks -------------------------------------------------*/
 221
 222 #ifdef __cplusplus
 223   }
 224 #endif
 225
 226 #endif