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