chiark / gitweb /
Initial revision
[mLib] / track.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
3 * $Id: track.h,v 1.1 1998/06/17 23:44:42 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 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.
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 General Public License for more details.
23 *
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.
27 */
28
29/*----- Revision history --------------------------------------------------*
30 *
31 * $Log: track.h,v $
32 * Revision 1.1 1998/06/17 23:44:42 mdw
33 * Initial revision
34 *
35 */
36
37#ifndef TRACK_H
38#define TRACK_H
39
40#ifdef __cplusplus
41 extern "C" {
42#endif
43
44#include <stdlib.h>
45
46/*----- Options and conventions -------------------------------------------*
47 *
48 * The following macros affect the tracking system:
49 *
50 * @TRACK_ENABLE@: Enable tracking of memory allocations
51 * @TRACK_BLAME@: Register my context blocks in allocations
52 *
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.
61 *
62 * Got it? Good.
63 */
64
65/*----- Type definitions --------------------------------------------------*/
66
67/* --- A context buffer --- */
68
69typedef struct track_ctx {
70 struct track_ctx *next;
71 const char *s;
72} track_ctx;
73
74/*----- Functions provided ------------------------------------------------*/
75
76/* --- @track_setLevel@ --- *
77 *
78 * Arguments: @unsigned int l@ = tracing level for allocation messages
79 *
80 * Returns: ---
81 *
82 * Use: Sets the trace level for allocation messages.
83 */
84
85extern void track_setLevel(unsigned int /*l*/);
86
87/* --- @track_pushContext@ --- *
88 *
89 * Arguments: @track_ctx *ctx@ = context holder to push
90 *
91 * Returns: ---
92 *
93 * Use: Pushes the given context block onto the stack.
94 */
95
96extern void track_pushContext(track_ctx */*ctx*/);
97
98/* --- @track_popContext@ --- *
99 *
100 * Arguments: @track_ctx *ctx@ = context holder to pop
101 *
102 * Returns: ---
103 *
104 * Use: Removes the given context block from the stack.
105 */
106
107extern void track_popContext(track_ctx */*ctx*/);
108
109/* --- @track_malloc@ --- *
110 *
111 * Arguments: @size_t sz@ = size requested
112 *
113 * Returns: Pointer to allocated space, or null
114 *
115 * Use: Allocates memory, and tracks how much is allocated.
116 */
117
118extern void *track_malloc(size_t /*sz*/);
119
120/* --- @track_free@ --- *
121 *
122 * Arguments: @void *p@ = pointer to an allocated block
123 *
124 * Returns: ---
125 *
126 * Use: Frees memory, and tracks how much is still allocated.
127 */
128
129extern void track_free(void */*p*/);
130
131/* --- @track_realloc@ --- *
132 *
133 * Arguments: @void *p@ = pointer to an allocated block
134 * @size_t sz@ = how big it wants to be
135 *
136 * Returns: Pointer to the new block.
137 *
138 * Use: Reallocates a block, tracking how much memory is still
139 * available.
140 */
141
142extern void *track_realloc(void */*p*/, size_t /*sz*/);
143
144/* --- @track_used@ --- *
145 *
146 * Arguments: ---
147 *
148 * Returns: A count of how much memory is used currently.
149 *
150 * Use: Returns the amount of memory which the @track_@-functions
151 * above have counted as being currently allocated.
152 */
153
154extern unsigned long track_used(void);
155
156/* --- @track_list@ --- *
157 *
158 * Arguments: @unsigned int l@ = trace level to use
159 *
160 * Returns: ---
161 *
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
166 * picnic, though.
167 */
168
169extern void track_list(unsigned int l);
170
171/*----- Macro wrappers ----------------------------------------------------*/
172
173
174/* --- If tracking is to be done, set it up --- */
175
176#ifdef TRACK_ENABLE
177# undef malloc
178# define malloc(sz) track_malloc(sz)
179# undef free
180# define free(p) track_free(p)
181# undef realloc
182# define realloc(p, sz) track_realloc(p, sz)
183#endif
184
185/* --- Provide a context for doing track-related things --- */
186
187#ifdef TRACK_ENABLE
188# define TRACK(x) x
189#else
190# define TRACK(x)
191#endif
192
193/* --- Handle contexts --- */
194
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)
202#else
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)
209#endif
210
211/*----- That's all, folks -------------------------------------------------*/
212
213#ifdef __cplusplus
214 }
215#endif
216
217#endif