page@swan.ulowell.edu (Bob Page) (02/01/89)
Submitted-by: karl@sugar.uu.net (Karl Lehenbauer)
Posting-number: Volume 89, Issue 7
Archive-name: util/tracker.1
Even though in an alpha state, I think this will be of great use to
Aztec C programmers who want to be sure they're freeing all of their
memory. It also helps locate where the problem is; it prints out the
file name and line number where each AllocMem was performed that did
not have a matching FreeMem, for example.
# This is a shell archive.
# Remove everything above and including the cut line.
# Then run the rest of the file through sh.
#----cut here-----cut here-----cut here-----cut here----#
#!/bin/sh
# shar: Shell Archiver
# Run the following text with /bin/sh to create:
# README
# tracker.h
# tracker.c
# This archive created: Mon Jan 30 17:24:47 1989
cat << \SHAR_EOF > README
C Programmer's Amiga Resource Tracking Routines Version 0.0a 1/5/89
-------------------------------------------------------------------------
This code and documentation is released to the Public Domain without any
restrictions on use, resale or redistribution.
No license or warranty of appropriateness, usefulness or bug-freeness is
expressed or implied. This is free code. We don't have a contract.
Written by:
Karl Lehenbauer, Hackercorp, 3918 Panorama, Missouri City, TX, USA 77459
(713) 438-4964 voice, (713) 438-5018 data
Usenet: uunet!sugar!karl, Internet: karl@sugar.uu.net, BIX: kelehen
These routines were written to aid C programmers in insuring that their
programs are properly returning all the memory, signals and locks they
have allocated.
To use them, include tracker.h in your C source programs and recompile.
(The use of an "includes.c" along with the Manx +i and +h flags to
precompile the symbol table obviates the necessity of editing
'#include "tracker.h">' into every one of your source files.)
Next, edit your exit routine to call TrackerExitReport() after it has
freed everything. Then, compile tracker.c using the memory model you're
using for the rest of your code and link your program to include tracker.o.
(This can all be done in your makefile if you've got it set up right.)
Finally, run your program.
The program must either be initiated from the CLI or you must edit your
program's startup code to fopen stderr and direct it somewhere (like
to a window or a file) or you won't get any of the resource tracker's
messages, or worse.
As your program runs, every time it allocs memory via AllocMem(), allocs
a signal via AllocSignal() or gets a Lock via Lock(), special tracking
routines execute instead (thanks to some macros defined by tracker.h)
which, in addition to performing the action you requested, record
information about what you requested and what you got. For AllocMem(),
the source file and line of the AllocMem call as well as the amount of memory
requested and the pointer to the memory returned are recorded. For
AllocSignal(), only the signal numbers allocated are recorded at this time.
For Lock(), the file name to be locked, source file and line number and
the lock returned are recorded.
When your program frees memory via FreeMem(), a special tracking version
of FreeMem is executed that searches the list of entries recorded by the
tracking version of AllocMem(). The resource tracker reports if you free
something more than once, if you free something that you didn't allocate
or if the length that you are freeing differes from what you allocated.
This includes the source file name and line number of the matching AllocMem
(when it is known) and always includes the source file and line for FreeMem.
When your program frees a signal via FreeSignal(), a tracking version
of FreeSignal checks to see if you have allocated the signal you are
now freeing. If you haven't, it reports it, but it doesn't include the
file name and line number at this time. I don't think this is a serious
problem, as signals aren't as critical as the other stuff, but I may add
it in a future version.
When your program unlocks a lock via UnLock(), a tracking version of UnLock
searches the list of recorded locks to see if you locked the lock you are
unlocking and report accordingly.
The tracker exit report provided by TrackerExitReport() is where most of
the bugs are identified. TrackerExitReport identifies all AllocMems that
didn't have a corresponding FreeMem, including the source file and line
of the call to AllocMem as well as the address and size of the memory
in question. The resource tracker does not free the memory for you because
you may have not freed the memory on purpose (for example, you may have
spawned a task that uses it will free it later) and it cannot know that.
The exit report details all signals that weren't freed. This isn't very
important, in my opinion.
Also, the exit report prints information on all file locks that were made
that didn't have a corresponding UnLock. This information includes the
name of the file, value of the lock and the source file and line of the
code that locked it.
The exit report also prints the number of calls to allocate and free memory,
allocate and free signals and to lock and unlock files as a gross indicator
of whether you're cleaning everything up properly.
Note that, in the default configuration, memory that is freed and
reallocated will screw up the tracker because the tracker continues
to track memory objects after they have been freed. This is a tradeoff
between being to be able to detect multiple frees of the same memory or
not. If that's a problem, tracker.c can be recompiled with a
-DFORGET_MEMORY_WHEN_FREED option so that it will not try to detect
multiple frees.
The same is true for the lock tracking routines, although in that case
the argument is more clear that unlocks should cause the lock tracking
entry to be discarded, because multiple unlocks are common and multiple
locks and unlocks of the same file during execution are also conceivably
pretty common. Right now by default, the tracker will track locks after
they have been freed. To change this behavior, recompile tracker.c with
the -DFORGET_LOCKS_WHEN_UNLOCKED option.
Unfortunately, the tracker macros that redefine AllocMem and such will
cause your compiler to barf on any files you have that declare them
as external. If that happens, either remove the external declarations
(and include <functions.h>) or move them to be before the include of
tracker.h.
ALPHA RELEASE, SOFTWARE STATUS
------------------------------
The Lock, Unlock and DupLock tracking routines have not been tested
adequately. The signal stuff works OK, but that's no biggie. The
main thing of interest is the tracking AllocMem and FreeMem, which
I have used successfully on several programs that I have been working
on.
-karl @ The Hacker's Haven, Houston, TX -- 5-Jan-89
P.S. Note that TrackerExitReport() must be called to get the tracking
routines to free the memory they have allocated, so it's a good idea
to call it from your abnormal exit (_abort, etc) routines as well as
normal exit. Also, that's good because you can make sure you're freeing
properly from your strange abort conditions, a thing that's hard to get
right.
SHAR_EOF
cat << \SHAR_EOF > tracker.h
/* tracking macros to use tracker routines */
#define AllocMem(x,y) TrackingAllocMem(x,y,__FILE__,__LINE__)
#define FreeMem(x,y) TrackingFreeMem(x,y,__FILE__,__LINE__)
#define AllocSignal(x) TrackingAllocSignal(x,__FILE__,__LINE__)
#define FreeSignal(x) TrackingFreeSignal(x,__FILE__,__LINE__)
#define Lock(x,y) TrackingLock(x,__FILE__,__LINE__)
#define UnLock(x,y) TrackingUnLock(x,__FILE__,__LINE__)
#define DupLock(x) TrackingDupLock(x,__FILE__,__LINE__)
void *TrackingAllocMem();
void TrackingFreeMem();
long TrackingAllocSignal();
void TrackingFreeSignal();
void *TrackingAllocRaster();
void TrackingFreeRaster();
struct FileLock *TrackingLock();
void TrackingUnLock();
SHAR_EOF
cat << \SHAR_EOF > tracker.c
/* tracking memory allocator */
#include <exec/types.h>
#include <exec/memory.h>
#include <functions.h>
#include <stdio.h>
/* comment out the following line if you want locks freed twice reported
* at the cost of getting spurious resource error messages when
* reusing the lock */
/* #define FORGET_LOCKS_WHEN_UNLOCKED */
/* comment out the following line if you want memory freed twice reported
* at the cost of getting spurious resource error messages when
* freeing and reallocating memory */
/* #define FORGET_MEMORY_WHEN_FREED */
/* make sure our invocations of the real routines on behalf of the user
don't cause us to recurse */
#ifdef AllocMem
#undef AllocMem
#undef FreeMem
#undef AllocSignal
#undef FreeSignal
#undef Lock
#undef UnLock
#undef DupLock
#endif
/* my flags */
#define FREED_IT 1
struct TrackingAllocMemData
{
UBYTE *where; /* address returned by allocator */
long amount; /* number of bytes allocated */
long alloc_flags; /* flags passed to allocator */
char *file; /* filename of caller from the macro */
int line; /* line number of caller from macro */
long my_flags; /* flags internal to tracker */
struct TrackingAllocMemData *next; /* pointer to next entry */
};
struct TrackingAllocMemData *TrackingAllocMemList = NULL;
long MemAllocCount = 0, MemFreeCount = 0;
void *TrackingAllocMem(amount,flags,file,line)
long amount;
long flags;
char *file;
int line;
{
register struct TrackingAllocMemData *rp;
UBYTE *users_memory;
/* perform the actual alloc */
users_memory = AllocMem(amount,flags);
/* if it succeeded, record tracking info */
if (users_memory)
{
MemAllocCount++;
if ((rp = AllocMem((long)sizeof(struct TrackingAllocMemData),0L)) == NULL)
panic("tracker: can't alloc memory to record AllocMem data");
/* add new alloc data entry to linked list */
rp->next = TrackingAllocMemList;
TrackingAllocMemList = rp;
/* shove in save values */
rp->amount = amount;
rp->alloc_flags = flags;
rp->where = users_memory;
rp->file = file;
rp->line = line;
rp->my_flags = 0;
}
/* return pointer to the space allocated */
return(users_memory);
}
void TrackingFreeMem(where,amount,file,line)
UBYTE *where;
long amount;
char *file;
int line;
{
register struct TrackingAllocMemData *rp, *op, *freep;
MemFreeCount++;
/* scan the memory tracking list for a match */
for (rp = TrackingAllocMemList, op = NULL; rp != NULL; op = rp, rp = rp->next)
{
/* if we matched the address */
if (rp->where == where)
{
/* if they got the amount wrong, tell them */
if (rp->amount != amount)
{
fprintf(stderr,"freed addr %lx OK but length differs, talloc'ed %ld, freed %ld,\n\tallocated at file %s line %d, freed at file %s line %d\n",
where,rp->amount,amount,rp->file,rp->line,file,line);
}
#ifndef FORGET_MEMORY_WHEN_FREED
/* if it's already free, tell them they freed twice */
if (rp->my_flags & FREED_IT)
{
fprintf(stderr,"freed memory twice at %lx, amount %ld,\n\tallocated in file %s at line %d, freed in file %s at line %d\n",where,amount,rp->file,rp->line,file,line);
return;
}
else
{
/* mark this entry as free */
rp->my_flags |= FREED_IT;
}
#else
/* remove entry from linked list and free it */
if (op != NULL) op->next = rp->next;
else
TrackingAllocMemList = rp->next;
freep = rp;
rp = rp->next;
FreeMem(freep,(long)sizeof(struct TrackingAllocMemData));
#endif
FreeMem(where,amount);
return;
}
}
fprintf(stderr,"Freed memory at %lx of amount %ld that wasn't allocated,\n\tfreed at file %s line %d\n",where,amount,file,line);
FreeMem(where,amount);
}
void ReportUnfreedMemory()
{
struct TrackingAllocMemData *rp = TrackingAllocMemList, *freep;
while (rp != NULL)
{
if (!(rp->my_flags & FREED_IT))
{
fprintf(stderr,"FreeMem was never called for memory at %lx, amount %ld,\n\tthe alloc was performed at file %s line %d\n",rp->where,rp->amount,rp->file,rp->line);
}
freep = rp;
rp = rp->next;
FreeMem(freep,(long)sizeof(struct TrackingAllocMemData));
}
printf("Total tracked AllocMem calls %ld, FreeMem calls %ld\n",MemAllocCount,MemFreeCount);
}
/* track signals */
/* tracking AllocSignal doesn't currently track where it was called from */
long TrackingSignalMask = 0;
long SignalAllocCount = 0, SignalFreeCount = 0;
long TrackingAllocSignal(signal_num,file,line)
long signal_num;
char *file;
int line;
{
SignalAllocCount++;
signal_num = AllocSignal(signal_num);
if (signal_num != -1)
TrackingSignalMask |= (1 << signal_num);
return(signal_num);
}
void TrackingFreeSignal(signal_num,file,line)
long signal_num;
char *file;
int line;
{
SignalFreeCount++;
if (!(TrackingSignalMask & (1 << signal_num)))
{
fprintf("freed a signal (%ld) that was never allocated, at file %s line %d\n",
signal_num,file,line);
TrackingSignalMask &= ~(1 << signal_num);
}
}
void ReportUnfreedSignals()
{
if (TrackingSignalMask)
fprintf("failed to free signals indicated by this mask: %8lx\n",
TrackingSignalMask);
printf("Total tracked AllocSignal calls %ld, FreeSignal calls %ld\n",SignalAllocCount,SignalFreeCount);
}
/* tracking lock and unlock */
struct TrackingLockData
{
struct FileLock *lock; /* lock returned by Lock */
char *name; /* name of file that was locked */
long accessMode; /* access mode of the file that was locked */
char *file; /* ptr to file name of line of caller */
int line; /* ptr to line number text of locker */
long my_flags; /* flags internal to tracker */
struct TrackingLockData *next; /* pointer to next entry */
};
/* flags */
#define CREATED_BY_DUPLOCK 1
struct TrackingLockData *TrackingLockList = NULL;
long TrackerLockCount = 0, TrackerUnLockCount = 0;
struct FileLock *TrackingLock(name, accessMode, file, line)
char *name;
long accessMode;
char *file;
int line;
{
register struct TrackingLockData *lp;
struct FileLock *users_lock;
users_lock = Lock(name, (long)accessMode);
if (users_lock)
{
TrackerLockCount++;
if ((lp = AllocMem((long)sizeof(struct TrackingLockData),0L)) == NULL)
panic("tracker: can't alloc memory to record lock data");
/* add new alloc data entry to linked list */
lp->next = TrackingLockList;
TrackingLockList = lp;
/* shove in save values */
lp->accessMode = accessMode;
lp->file = file;
lp->line = line;
lp->my_flags = 0;
lp->lock = users_lock;
/* alloc space for filename and save */
if ((lp->name = AllocMem((long)(strlen(name)+1),0L)) == NULL)
panic("tracker: can't alloc memory to record lock filename");
strcpy(lp->name,name);
}
return(users_lock);
}
struct FileLock *TrackingDupLock(lock, file, line)
struct FileLock *lock;
char *file;
int line;
{
register struct TrackingLockData *lp;
struct FileLock *users_lock;
users_lock = DupLock(lock);
if (users_lock)
{
TrackerLockCount++;
if ((lp = AllocMem((long)sizeof(struct TrackingLockData),0L)) == NULL)
panic("tracker: can't alloc memory to record lock data");
/* add new alloc data entry to linked list */
lp->next = TrackingLockList;
TrackingLockList = lp;
lp->file = file;
lp->line = line;
lp->name = NULL;
lp->lock = users_lock;
lp->my_flags = CREATED_BY_DUPLOCK;
}
return(users_lock);
}
void TrackingUnLock(lock,file,line)
struct FileLock *lock;
char *file;
int line;
{
register struct TrackingLockData *lp, *op, *freep;
TrackerUnLockCount++;
/* scan the lock tracking list for a match */
for (lp = TrackingLockList, op = NULL; lp != NULL; op = lp, lp = lp->next)
{
/* if we matched the lock */
if (lp->lock == lock)
{
#ifndef FORGET_LOCKS_WHEN_UNLOCKED
/* if it's already free, tell them they freed twice */
if (lp->my_flags & FREED_IT)
{
fprintf(stderr,"freed lock twice, lock %lx, filename %s\n\tlocked at file %s line %d, freed at file %s line %d\n",lock,lp->name,lp->file,lp->line,file,line);
return;
}
else
{
/* mark this entry as free */
lp->my_flags |= FREED_IT;
}
#else
if (op != NULL) op->next = lp->next;
else TrackingLockList = lp->next;
freep = lp;
lp = lp->next;
if (lp->name != NULL)
FreeMem(lp->name,(long)(strlen(lp->name)+1));
FreeMem(freep,(long)(sizeof(struct TrackingLockData)));
#endif
UnLock(lock);
return;
}
}
fprintf(stderr,"Freed lock %lx that hadn't been allocated at file %s line %d\n",lock,file,line);
}
ReportUnfreedLocks()
{
struct TrackingLockData *lp = TrackingLockList, *freep;
while (lp != NULL)
{
if (!(lp->my_flags & FREED_IT))
{
if (lp->my_flags & CREATED_BY_DUPLOCK)
{
fprintf(stderr,"UnLock was never called for lock %lx,\n\It was created by DupLock at file %s line %d\n",lp->lock,lp->file,lp->line);
}
else
{
fprintf(stderr,"UnLock was never called for lock %lx,\n\It was created by a Lock of %s\nat file %s line %d\n",lp->lock,lp->name,lp->file,lp->line);
}
}
if (lp->name != NULL)
FreeMem(lp->name,(long)(strlen(lp->name)+1));
freep = lp;
lp = lp->next;
FreeMem(freep,(long)sizeof(struct TrackingLockData));
}
printf("Total tracked Lock and DupLock calls %ld, UnLock calls %ld\n",TrackerLockCount,TrackerUnLockCount);
}
TrackerExitReport()
{
ReportUnfreedMemory();
ReportUnfreedLocks();
ReportUnfreedSignals();
}
SHAR_EOF
# End of shell archive
exit 0
--
Bob Page, U of Lowell CS Dept. page@swan.ulowell.edu ulowell!page
Have five nice days.