chiark / gitweb /
Infrastructure: Split the files into subdirectories.
[mLib] / mem / track.h
CommitLineData
0875b58f 1/* -*-c-*-
2 *
0875b58f 3 * Tracing functions for debugging
4 *
5 * (c) 1998 Straylight/Edgeware
6 */
7
d4efbcd9 8/*----- Licensing notice --------------------------------------------------*
0875b58f 9 *
10 * This file is part of the mLib utilities library.
11 *
12 * mLib is free software; you can redistribute it and/or modify
c846879c 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.
d4efbcd9 16 *
0875b58f 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
c846879c 20 * GNU Library General Public License for more details.
d4efbcd9 21 *
c846879c 22 * You should have received a copy of the GNU Library General Public
0bd98442 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.
0875b58f 26 */
27
c6e0eaf0 28#ifndef MLIB_TRACK_H
29#define MLIB_TRACK_H
0875b58f 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
60typedef struct track_ctx {
61 struct track_ctx *next;
62 const char *s;
63} track_ctx;
64
65/*----- Functions provided ------------------------------------------------*/
66
94a27cd6 67/* --- @track_level@ --- *
0875b58f 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
94a27cd6 76extern void track_level(unsigned int /*l*/);
0875b58f 77
94a27cd6 78/* --- @track_push@ --- *
0875b58f 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
94a27cd6 87extern void track_push(track_ctx */*ctx*/);
0875b58f 88
94a27cd6 89/* --- @track_pop@ --- *
0875b58f 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
94a27cd6 98extern void track_pop(track_ctx */*ctx*/);
0875b58f 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
109extern 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
120extern 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
133extern 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
145extern 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
160extern void track_list(unsigned int l);
161
162/*----- Macro wrappers ----------------------------------------------------*/
163
0875b58f 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)
94a27cd6 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)
0875b58f 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