

                      SNOOP v1.01 for Delphi 2.x
                      ~~~~~~~~~~~~~~~~~~~~~~~~~~

                       by Robert R. Marsh, S.J.


At last -- a way to check for memory leaks in Delphi 2 that doesn't
cost the earth!


What SNOOP Does
~~~~~~~~~~~~~~~

Commercial products like Memory Sleuth and BoundsChecker allow you
to check your programs for all the pointers you thought you had
freed but hadn't. They check for all sorts of other problems too.
Unfortunately, I know of no utility of this kind that is FREE, so
until now I've just had to make do and hope for the best. Eventually,
though, I decided to try and write my own. SNOOP is the result.

SNOOP interfaces smoothly with your programs and takes note of all
memory allocations and deallocations and where in your code they
occur. When your program ends SNOOP creates a list of all the memory
blocks that didn't get deallocated and dumps it to a file.

SNOOP checks for memory handled by:

      ~ The GetMem, ReallocMem, and FreeMem standard procedures
      ~ The New and Dispose standard procedures
      ~ Allocation and deallocation of objects through constructors
        and destructors
      ~ Allocation and deallocation of dynamic strings


How to Use SNOOP
~~~~~~~~~~~~~~~~

1) SNOOP.DCU must be in a directory accessible by your project.

2) Make SNOOP the FIRST unit referenced in the USES clause of
   your program's PROJECT (*.DPR) file. E.g.,

       program snooper;

       uses
         Snoop,
         Forms,
         other in 'other.pas' {Form1};
       ...

3) Change your projects compiler and linker options:

      ~ The stack frames compiler directive must be ON
      ~ The debug information compiler directive must be ON
      ~ The linker should be set to generate a DETAILED MAP file

   If you forget the map file or the stack frames SNOOP will tell
   you so with an exception. If there is no debug information you
   just won't get any output.

4) Build your program and run it. When your application terminates
   it will produce a file (by default, SNOOP.LOG) with the following
   format:

       SNOOP Report on SNOOPER.EXE generated at 4/20/1997 7:30:15 PM

       Memory Not Freed:
       filename     line    #ptrs    bytes
       other         40       2        26
       other         49       1       100
       other         50       1       150

   "Filename" and "line" show the location of any dangling pointers.
   The "#ptrs" column tells you how many pointers were allocated at
   that location, while "bytes" reports the aggregate size of the
   memory leak.

   If you wish to change the name or location of the log file you
   can simply assign the new filename to the Snoop.SnoopLogFile
   variable.


5) The SNOOP memory manager can be switched off or on via the
   Snoop.Switch procedure. The current status of the memory manager
   is returned by the Snoop.Snooping function. To use these routines
   within a unit SNOOP must be referenced in the unit's USES clause.
   In these cases it doesn't matter whethr SNOOP comes first or not.

   In normal operation the SNOOP memory manager is actively snooping
   on memory allocations from the very first moments of your program's
   execution but this behavior can be overridden by supplying as a
   command-line parameter 'NoSnooping'. E.g., if your program is
   called snooper:

       snooper nosnooping

   If you initiate your program with snooping deactivated you can
   then switch snooping on selectively. For example, in your main
   form's Create and Destroy events:

       procedure TForm1.FormCreate(Sender: TObject);
       begin
       Snoop.Switch(Onn);
       end;

       procedure TForm1.FormDestroy(Sender: TObject);
       begin
       Snoop.Switch(Off);
       end;

   Notice the predefined constants Onn (not a misspelling!) and Off
   (TRUE and FALSE, respectively). You need to take care when
   switching SNOOP on and off that you place the switches in such a
   way that you expect the program's memory to be in the same state
   at each point. If you mismatch them the results will be, at best,
   misleading and, at worst, give rise to exceptions.


Issues
~~~~~~

1) SNOOP will slow your program down considerably. Don't be surprised
   if you have to wait a while for the program to load initially or if
   memory intensive tasks grind along slowly (e.g., filling a string
   list with thousands of items). You should, for this reason, remove
   SNOOP from your finished application.

2) SNOOP will baulk at any program that has more than 10,000 pointers
   allocated (and snooped on, that is) at any one time. Let me know if
   you ever reach this limit and it can be changed. I considered various
   schemes for allowing the capacity to grow as needed but, in each case,
   the performance of SNOOP dropped unacceptably.

3) Don't turn off debug information for any of the units in your program.
   SNOOP expects a certain layout of the map file. Let me know if this
   proves to be a problem.

4) SNOOP doesn't always get it right! SNOOP is occasionally a line out
   in its judgment of where an allocation was made. Moreover, problems
   deep in the VCL often emerge into your programs code space in places
   that tell you little, like the 'end;' statements of routines or
   in the projects code. The 'Application.Run;' line in the project is
   a favorite location! The VCL does have numerous memory leaks which
   are on the whole harmless but do show up in SNOOP.

5) SNOOP is new. I am sure you will find bugs or cases in which it fails
   to work properly. I can't see how it could damage your work but be
   warned -- in programming anything is possible. Use SNOOP at your own
   risk. I make no legally-binding promises whatsoever about SNOOP's
   behavior or usefulness (sorry!).


Finally ...
~~~~~~~~~~~

SNOOP is made available for no charge. You may use it and distribute
it freely as long as you make no charge for it and you include the
accompanying files.

If you like SNOOP and find it useful you might like to make a small
donation to your favorite charity. I always like to hear from users
with comments, suggestions, or even bug-reports. I can be contacted
at:
                         robmarsh@aol.com

The web page below is the home of my Quick DataBase (QDB) components for
Delphi 1 & 2. Stop by and take a look:

              http://members.aol.com/robmarsh/qdb.htm


SNOOP is copyright 1997, Robert R. Marsh, S.J. and the British
Province of the Society of Jesus. All rights reserved.

April 20, 1997
