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