3 * $Id: track.h,v 1.1 1998/06/17 23:44:42 mdw Exp $
5 * Tracing functions for debugging
7 * (c) 1998 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
14 * mLib is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
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 General Public License for more details.
24 * You should have received a copy of the GNU General Public License
25 * along with mLib; if not, write to the Free Software Foundation,
26 * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
29 /*----- Revision history --------------------------------------------------*
32 * Revision 1.1 1998/06/17 23:44:42 mdw
46 /*----- Options and conventions -------------------------------------------*
48 * The following macros affect the tracking system:
50 * @TRACK_ENABLE@: Enable tracking of memory allocations
51 * @TRACK_BLAME@: Register my context blocks in allocations
53 * The reason there are two switches is simple. It's often the case that a
54 * library routine allocates memory for its client. Therefore, whether we
55 * want to record the library or the client depends on how much we trust
56 * the two pieces of software. Setting @TRACK_ENABLE@ and @TRACK_BLAME@
57 * suggests that the current source file might leak memory, so we want its
58 * context markers in the list. Setting @TRACK_ENABLE@ but not
59 * @TRACK_BLAME@ suggests that we trust this code, but not the code which
60 * calls it, so we want to preserve the caller's context markers.
65 /*----- Type definitions --------------------------------------------------*/
67 /* --- A context buffer --- */
69 typedef struct track_ctx {
70 struct track_ctx *next;
74 /*----- Functions provided ------------------------------------------------*/
76 /* --- @track_setLevel@ --- *
78 * Arguments: @unsigned int l@ = tracing level for allocation messages
82 * Use: Sets the trace level for allocation messages.
85 extern void track_setLevel(unsigned int /*l*/);
87 /* --- @track_pushContext@ --- *
89 * Arguments: @track_ctx *ctx@ = context holder to push
93 * Use: Pushes the given context block onto the stack.
96 extern void track_pushContext(track_ctx */*ctx*/);
98 /* --- @track_popContext@ --- *
100 * Arguments: @track_ctx *ctx@ = context holder to pop
104 * Use: Removes the given context block from the stack.
107 extern void track_popContext(track_ctx */*ctx*/);
109 /* --- @track_malloc@ --- *
111 * Arguments: @size_t sz@ = size requested
113 * Returns: Pointer to allocated space, or null
115 * Use: Allocates memory, and tracks how much is allocated.
118 extern void *track_malloc(size_t /*sz*/);
120 /* --- @track_free@ --- *
122 * Arguments: @void *p@ = pointer to an allocated block
126 * Use: Frees memory, and tracks how much is still allocated.
129 extern void track_free(void */*p*/);
131 /* --- @track_realloc@ --- *
133 * Arguments: @void *p@ = pointer to an allocated block
134 * @size_t sz@ = how big it wants to be
136 * Returns: Pointer to the new block.
138 * Use: Reallocates a block, tracking how much memory is still
142 extern void *track_realloc(void */*p*/, size_t /*sz*/);
144 /* --- @track_used@ --- *
148 * Returns: A count of how much memory is used currently.
150 * Use: Returns the amount of memory which the @track_@-functions
151 * above have counted as being currently allocated.
154 extern unsigned long track_used(void);
156 /* --- @track_list@ --- *
158 * Arguments: @unsigned int l@ = trace level to use
162 * Use: Traces a dump of the currently known blocks. Combined with
163 * a verbose dump of allocations and deallocations, and a
164 * good idea of which blocks were allocated where, this can
165 * be useful for locating memory leaks. It's not exactly a
169 extern void track_list(unsigned int l);
171 /*----- Macro wrappers ----------------------------------------------------*/
174 /* --- If tracking is to be done, set it up --- */
178 # define malloc(sz) track_malloc(sz)
180 # define free(p) track_free(p)
182 # define realloc(p, sz) track_realloc(p, sz)
185 /* --- Provide a context for doing track-related things --- */
193 /* --- Handle contexts --- */
195 #if defined(TRACK_ENABLE) && defined(TRACK_BLAME)
196 # define TRACK_NCTX(name, string) track__context name = { 0, string }
197 # define TRACK_NPUSH(name) track_pushContext(name)
198 # define TRACK_NPOP(name) track_popContext(name)
199 # define TRACK_CTX(string) TRACK_NCTX(track__localContext, string)
200 # define TRACK_PUSH TRACK_NPUSH(track__localContext)
201 # define TRACK_POP TRACK_NPOP(track__localContext)
203 # define TRACK_NCTX(name, string)
204 # define TRACK_NPUSH(name) ((void)0)
205 # define TRACK_NPOP(name) ((void)0)
206 # define TRACK_CTX(string)
207 # define TRACK_PUSH ((void)0)
208 # define TRACK_POP ((void)0)
211 /*----- That's all, folks -------------------------------------------------*/