chiark / gitweb /
Qualify name given to @bres_byname@.
[mLib] / track.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
c6e0eaf0 3 * $Id: track.h,v 1.5 1999/12/10 23:42:04 mdw Exp $
0875b58f 4 *
5 * Tracing functions for debugging
6 *
7 * (c) 1998 Straylight/Edgeware
8 */
9
c846879c 10/*----- Licensing notice --------------------------------------------------*
0875b58f 11 *
12 * This file is part of the mLib utilities library.
13 *
14 * mLib is free software; you can redistribute it and/or modify
c846879c 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 *
0875b58f 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
c846879c 22 * GNU Library General Public License for more details.
23 *
24 * You should have received a copy of the GNU Library General Public
0bd98442 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.
0875b58f 28 */
29
30/*----- Revision history --------------------------------------------------*
31 *
32 * $Log: track.h,v $
c6e0eaf0 33 * Revision 1.5 1999/12/10 23:42:04 mdw
34 * Change header file guard names.
35 *
94a27cd6 36 * Revision 1.4 1999/10/22 22:40:25 mdw
37 * Change naming slightly. Still not documented, though.
38 *
0bd98442 39 * Revision 1.3 1999/05/06 19:51:36 mdw
40 * Reformatted the LGPL notice a little bit.
41 *
c846879c 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
0875b58f 47 *
48 */
49
c6e0eaf0 50#ifndef MLIB_TRACK_H
51#define MLIB_TRACK_H
0875b58f 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
82typedef struct track_ctx {
83 struct track_ctx *next;
84 const char *s;
85} track_ctx;
86
87/*----- Functions provided ------------------------------------------------*/
88
94a27cd6 89/* --- @track_level@ --- *
0875b58f 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
94a27cd6 98extern void track_level(unsigned int /*l*/);
0875b58f 99
94a27cd6 100/* --- @track_push@ --- *
0875b58f 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
94a27cd6 109extern void track_push(track_ctx */*ctx*/);
0875b58f 110
94a27cd6 111/* --- @track_pop@ --- *
0875b58f 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
94a27cd6 120extern void track_pop(track_ctx */*ctx*/);
0875b58f 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
131extern 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
142extern 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
155extern 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
167extern 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
182extern void track_list(unsigned int l);
183
184/*----- Macro wrappers ----------------------------------------------------*/
185
0875b58f 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)
94a27cd6 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)
0875b58f 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