ExamineStorageDoc.tioga
Mike Spreitzer:PARC:Xerox, December 4, 1990 2:07 pm PST
Bier, June 20, 1990 3:53 pm PDT
Michael Plass, October 5, 1992 3:33 pm PDT
Willie-s, March 16, 1993 2:24 pm PST
ExamineStorage
CEDAR10.1 — FOR INTERNAL XEROX USE ONLY
ExamineStorage
Heap Scanning Utilities
Russ Atkinson, Mike Spreitzer, Michael Plass
© Copyright 1990, 1991, 1993 Xerox Corporation. All rights reserved.
Abstract: ExamineStorage provides a command that enumerates the heap, and prints out statistics on the N most memory-consuming TYPEs of objects. This is a pale reflection of the glory of the DCedar package.
Created by: Russ Atkinson in DCedar, Mike Spreitzer in PCedar.
Maintained by: Your Name Here <PCedarImplementors:PARC:Xerox>
Keywords: Heap, Examine, Memory
XEROX  Xerox Corporation
   Palo Alto Research Center
   3333 Coyote Hill Road
   Palo Alto, California 94304

For Internal Xerox Use Only
1. User Interface
ExamineStorage [ N [ margin ] ]
The command `ExamineStorage' insists on exactly one argument, an integer we'll call N. This command enumerates the whole heap, summing up, for each typecode, the size and number of objects with that typecode. Note that our allocator doesn't distinguish between objects that have typecodes and those that don't, so sometimes random data will be interpreted as typecodes; I think that rarely leads to large errors in the resulting statistics. After the heap scan, the information is sorted by typecode, and the grand totals and the information for the N most memory-consuming typecodes is printed. The margin controls the prettyprinting of the results.
It seems to scan the heap pretty quickly. In my testing, it's taken only a few seconds. For example, 3.5 for a 15 megabyte, 15 kilo-object heap, on my SPARCstation 2. The first invocation seems to take longer than the rest.
Printing of the result
This section needs updating; the printing is actually a little better than this documentation indicates, if a suitable version map is available.
Currently, type printing stops short of what you'd want. Specifically, for a Cedar `painted' TYPE, the `paint' is printed, rather than what is tagged with that paint. This will probably improve soon. In the meantime, for those interested, here's how you can dereference paint. For example, the paint printed as `73FBB1B90F74263A:ctx4E8'. First, use VM2LS to find out which mob is represented by 73FBB1B90F74263A, and get its `details', like this:

% VM2LS $Intermediate * * 73FBB1B90F74263A
/PCedar2.0/Rope/Rope.mob!3 of March 7, 1989 13:03:35 PST ver 73FBB1B90F74263A
% MobDetails /PCedar2.0/Rope/Rope.mob!3
Mob details of [pcedar2.0]<Rope>Rope.mob!3 output to Rope.details
% Open Rope.details
 Created Viewer: /net/palain/jaune/spreitzer/ES/Rope.details
%
In the mob details listing, look for the uses of, in this case, `ctx4E8'; here, it is the field context of the record type identified by `se2DC8'. Scanning for other occurrences of `se2DC8' reveals the definition of the TYPE `RopeRep' to be se2DC8. Thus, the paint `73FBB1B90F74263A:ctx4E8' means Rope(version stamped 73FBB1B90F74263A).RopeRep.
2. Other utilities
These things have proven to be useful for finding out why things don't get collected when you think they should be:

ExamineExamples
Finds a few things with the given typecode
-s <minBytes> <limitBytes>
(The size bounds let you concentrate on objects in a specific size range)
ExamineListSeeds Finds the seeds of lists with a given typecode
ExamineRecursiveRoots Finds things that point to things that point to ... a set of REFs
ExamineRoots Finds things that point to a REF
MemoryGrep target startAddr endAddr
MemoryDump Dump local memory:
MemoryDump startAddress [ byteCount ]
Parameters follow Cedar numeric literal syntax
3. See also
These commands actually live in the PrintTypeString component, but since there is no doc file for that one:

PrintTypeCode
Decodes SafeStorage.Type values
PrintTypeString Decodes a type string