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