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