ǷSyntax24b.Scn.FntParcElemsAlloc Syntax10.Scn.Fnt|pVersionElemsAllocBeg$Syntax24b.Scn.FntEnglish DeutschEnglishEnglish Deutsch$Syntax14b.Scn.Fnt DokumentationSyntax14b.Scn.FntpVersionElemsAllocEndSyntax8b.Scn.Fntj}4PElemsAllocBMv(XʦDtGDtGDUQUQqUQUQUQqqUQUQUQqqqUQUQUQqqqUQUQqUDtGDqtGQUQqUQUQqUQUDtGDqtGQqtGDtGDqqUQqtGDtGDtGDtGQqtGQUUUDtGDtGDUQUQqUQUQUQqqUQUQUQqqqUQUQUQqqqUQUQqUDtGDqtGQUQqUQUQqUQUDtGDqtGQqtGDtGDqqUQqtGDtGDtGDtGQqtGQUUUU^DLDDqqUQqUQUQUQqUQUQqtGDU\}̙U^DLDDqqUQqUQUQUQqUQUQqtGDU\}̙DUQtDqUQqqUDqtGDtGDqUQUDqtGDqUQqtGQUqUQUQtGDqtGDtGQqUQUQUQUDtGDqqqU]DUQtDqUQqqUDqtGDtGDqUQUDqtGDqUQqtGQUqUQUQtGDqtGDtGQqUQUQUQUDtGDqqqU]qtGDqtGDtGDqtGDqqqqqtGDtGDqtGDtGDUQUQUQqUQqUQqtGDUDtGQqqUQUQqtGDqU\qtGQqUQtGDtGQqUQtEQUDtLqtGDqtGDtGDqtGDqqqqqtGDtGDqtGDtGDUQUQUQqUQqUQqtGDUDtGQqqUQUQqtGDqU\qtGQqUQtGDtGQqUQtEQUDtLQUTGQUDtGQUQUDQUTGQUDtGQUQUDtGQUQUDtGDtGDtGDqtEQUQUQqUDtGDqqU^tGQUQUDtGDtGDtGDqtEQUQUQqUDtGDqqU^3=3=33}}np#Syntax10.Scn.FntEnglish DeutschEnglishEnglish Deutsch#Syntax10.Scn.Fnt von Martin Rammerstorfer (MR) p Yp$Syntax24b.Scn.FntEnglish DeutschEnglishEnglish Deutsch#Syntax10.Scn.Fnt11<== Bitte Sprache whlen / Please select language1p Z p#Syntax10.Scn.FntEnglish DeutschEnglishEnglish Deutsch$Syntax16b.Scn.FntInhaltSyntax16b.Scn.FntpSyntax12.Scn.Fnt  StampElemsAlloc25 May 97\n  'Ўp#Syntax10.Scn.FntEnglish DeutschEnglishEnglish DeutschSyntax12b.Scn.FntMarkElemsAllocLinkElemsAlloc* Syntax12.Scn.Fnt*n *x** * * * * *Syntax10.Scn.Fnt*(*6*@*** *!*"*<Syntax16.Scn.Fnt*Syntax16b.Scn.Fnt*&*. ZParcElemsAlloc   Zr Syntax14b.Scn.Fntn[x WzbSyntax12i.Scn.Fnt{*@| S%$ *x.] r h*1*?*LQ LHi     @  jg)*"F_3s6|*@> ZtMRz!$*6!*6(m*6*~*6 Y*PN6$I  *{ *|!Syntax8.Scn.Fnt +#e6Q$6"/ 7{#% #!$!. Z ( Zy  6][@*#*_b1. Menleiste 1.1 Close 1.2 HeapInspector 1.3 GC (Garbage Collector) 1.4 Info 1.5 Map 1.6 Show 1.7 Modules 1.8 Store 1.9 Help 2. Maus- und Tastaturhanhabung 2.1 Maushandhabung 2.2 Tastaturhandhabung 3. Implementierung 3.1 HeapInspector.Mod 3.1.1 Procedures for reset and set of data 3.1.2 Procedures for storing specified blocks on a set-array 3.1.3 Procedures for text operations 3.1.4 Procedures for module / type descriptor operations 3.1.5 Procedures for event-handling (selection) 3.1.6 Commands for setting the modes for Garbage-Collector 3.1.7 For miscellaneous use: MoveMap, DrawBlock, SetPtrReach, ReadMarkNames 3.1.8 Procedures for visualizing the objects on the heap on different criteria 3.1.9 Commands for update and marking objects 3.1.10 Commands for changing and showing the status of HeapInspector 3.2 HeapInspViewers.Mod 3.3 HeapInspDescs.Mod 3.4 HeapInspTracer.Mod 4. Autor Anhang A: Beschreibung der Kommandos in EBNF B: Beispiele fr die Benutzung des HeapInspectors 1. Die Menleiste 1.1. Close (HeapInspector.Close): Schliet den HeapInspector-Viewer. Wenn der geschlossene Viewer der zuletzt geffnete Viewer ist, wird der automatische Update der Bitmap nach jedem Garbage-Collector Durchlauf automatisch abgeschaltet. Nach dem Klicken auf HeapInspector.Close bietet der HeapInspector in der Menzeile zwei Alternativen an, um den HeapInspector zu beenden: - Close viewer: Schliet den momentanen viewer. - Unload modules of HeapInspector: Schliet den momentanen viewer und entldt alle Module, die der HeapInspector bentigt (d.h.: HeapInspViewers (sofern geladen), HeapInspector, HeapInspDescs und Inspector). 1.2. HeapInspector HeapInspector.Update: Bewirkt ein Update der Bitmap und zeigt die aktuell vorhandenen Objekte auf dem Heap. HeapInspector.HeapMap ~: ffnet einen HeapInspector-Viewer mit einer Bitmap die den Heap reprsentiert. Alte HeapInspector-Viewer bleiben sichtbar, aber alle Operationen in der Menzeile (der alten und neuen) Viewer beziehen sich auf den neuen Viewer. Der neue Viewer hat die gleichen Einstellungen wie der vorhergehende Viewer, nur da kein Objekt in der Bitmap markiert ist. Bemerkung: Wenn jemand einen neuen HeapInspector-Viewer ffnet, ohne den alten zu schlieen, wechselt die Bitmap im alten Viewer zu einer passiven Bitmap (PElems). HeapInspector.HeapMap ^: ffnet einen HeapInspector-Viewer wie oben beschrieben, die Parameter werden dabei von der letzten Selektion genommen. Der erste Parameter ist optional. Wenn der erste Parameter "NoSplash" ist, wird das Splash-window beim ersten Zeichnen der Bitmap nicht angezeigt. Der zweite Parameter ist ebenfalls optional, und legt die maximale Hhe der Bitmap in Pixel fest. Die aktuelle Hhe ist immer kleiner als die maximale Hhe, wobei jeder Block eine Abmessung von 1, 2, 4 oder 8 Pixel haben mu. Aus diesem Grund hat die Bitmap meist nicht die volle Hhe. Die Default-Hhe ist 220 Pixel. Die weiteren Parameter geben die Typen der Objekte an, die markiert werden sollen (siehe folgende Beschreibung). Dieser Typ besteht aus Modulname.Typname mit dem das Objekt deklariert ist. Wenn nur der Modulname angegeben wird, werden alle Objekte von den Typen, die in diesem Module deklariert sind, markiert. Wenn ein Stern der Typspezifikation folgt (z.B. Files*, Texts.ElemDesc*), ist diese eine Kurzschreibweise fr die spezifizierten Typen und den Typen, die von diesen abgeleitet wurden (d.h. Files.Handle, Files.Buffer, ..., Texts.ElemDesc, PopupElems.ElemDesc, ...). Jede Typspezifikation wird mit einer neuen Farbe dargestellt, die benutzt wird, um die entsprechenden Objekte einzufrben (Siehe auch Anhang A). Bemerkung: Die maximale Anzahl der Typspezifikationen betrgt 5. HeapInspector.HeapMarkObjects ^: Markiert die angegebenen Objekte wie oben, nur wird kein neuer Viewer geffnet. 1.3. GC (Garbage Collector) HeapInspector.GCOnOff on: Schaltet den Garbage-Collector an. HeapInspector.GCOnOff off: Schaltet den Garbage-Collector aus. HeapInspector.UpdateAfterGC on: Schaltet den automatischen Update der Bitmap ein, d.h. da der HeapInspector alle Bitmaps und Statistiken nach einer Garbage-Collection auffrischt. HeapInspector.UpdateAfterGC off: Schaltet den automatischen Update der Bitmap aus. Wenn der Garbage-Collector durchgelaufen ist, wird der Viewer nicht upgedated (Der explizite Update mit HeapInspector.Update ist nicht abgeschaltet). System.Collect: Initiiert einen Garbage-Collector Durchlauf wenn der Garbage-Collector eingeschaltet ist. 1.4. Info Die folgenden Viewer sind ein Schnappschu des aktuellen Heaps, d.h. whrend eines Update der Bitmaps werden diese Viewer nicht upgedated. HeapInspViewers.Modules: ffnet einen Viewer der die momentan geladenen Module und den Speicher, den das jeweilige Modul bentigt, anzeigt. Man kann die Liste dieser Module nach Name (aufsteigend), nach der Anzahl der Objekte und nach ihrer Gre (absteigend) sortieren, indem man den jeweiligen Menpunkt anwhlt. code: Speicherbedarf des Programmcodes, data: der Daten, refs: und der Referenzinformationen types: Anzahl der Typen. total memory used: Gesamter Speicherbedarf: Summe von Code, Daten, Referenzinformation, Moduldescriptorgre, ... is imported (dir / indir): Anzahl der Module, die direkt oder indirekt das angegebene Modul importieren. imports (dir / indir): Anzahl der Module, die von dem angegebenen Modul direkt oder indirekt importiert werden. Wenn ein Modul fr das Testweise-entladen (siehe Punkt 1.7) markiert wurde, stehen zwei Plus ("++") hinter der Anzahl der Importe. Wenn ein Modul ein Modul importiert, das fr das Testweise-entladen markiert ist, wird es ebenfalls entladen und mit einem einfachen Plus ("+") markiert. Wenn ein (und nur ein) Modul an der obersten Ebene der Modulhierarchie markiert wurde (siehe HeapInspector.TestUnloadModules), werden alle Module, die nur von diesem Modul bentigt werden (Funktioniert wie das Kommando "System.Free ModulName* ~"), mit einem Stern bei der Anzahl der Importe markiert. Diese Module werden aber nicht test-entladen. Wenn ein Modul indirekt importiert wird von einem test-entladenen Modul, If a module is directly imported by a test-unloaded module, there is a hash ("#") after the number of "imports". Bemerkung: Die Anzahl der direkten Importe stimmt manchmal nicht mit der Anzahl der Module in der Importliste im Sourcecode berein, dies liegt an der Art und Weise wie der Compiler die Importe auflst. Bemerkung: Wenn Module zum Test-entladen markiert wurden und ein Modul geladen oder entladen wird, werden alle Markierungen gelscht. HeapInspViewers.ObjectsByModule: ffnet einen Viewer, der die momentan geladenen Module mit der Anzahl und dem Speicherplatzbedarf der Objekte, deren Typ in diesem Modul definiert wurden. Man kann die Liste dieser Module nach Name (aufsteigend), nach der Anzahl der Objekte und nach ihrer Gre (absteigend) sortieren, indem man den jeweiligen Menpunkt anwhlt. HeapInspViewers.ObjectsByType: ffnet einen Viewer, der die Typen, die in den momentan geladenen Modulen definiert sind, anzeigt. Fr jeden Record-Typ wird die Anzahl der Objekte, die Anzahl der bentigten Bytes und die Anzahl der Bytes inklusive der Verluste durch die interne Fragmentierung aufgelistet (Die interne Fragmentierung wird dadurch verursacht, da die Speicherblcke nur in Vielfachen von 32 Bytes allokiert werden knnen). Man kann die Liste dieser Typen nach Name (aufsteigend), nach der Anzahl der Objekte und nach ihrer Gre (absteigend) sortieren, indem man den jeweiligen Menpunkt anwhlt. Bemerkung: Die Typen die keinen Typnamen haben, sind Typen die Lokal zu einer Prozedur deklariert wurden. HeapInspViewers.Imports: ffnet einen Viewer der die momentan geladenen Module auflistet. Wobei zu jedem Modul die zugehrige Importliste und die Module die dieses Modul importieren aufgelistet werden. Bemerkung: Die Anzahl der direkten Importe stimmt manchmal nicht mit der Anzahl der Module in der Importliste im Sourcecode berein, dies liegt an der Art und Weise wie der Compiler die Importe auflst. HeapInspViewers.ModuleHierarchy: ffnet einen Viewer der die Modulhierarchie anzeigt. Module, die keine anderen Module importieren, befinden sich in der Basis der Modulhierarchie (Level 0). Der Level der anderen Module ergibt sich aus dem Maximum der Level der von diesem Modul importierten Module plus 1: n Level (Modul (i)) := 1 + Maximum (Level (ImportierteModule (j))) j := 1 Module, die nicht mehr von anderen Modulen importiert werden, sind rot, Test-entladene Module sind blau und Module die indirekt von Test-entladenen Modulen importiert werden sind grn geschrieben (Blau hat dabei eine hhere Prioritt als rot). Die FoldElems hinter den Modulnamen enthalten die Liste der Module, die von dem jeweiligen Modul importiert werden. HeapInspViewers.TypeHierarchy: ffnet einen Viewer der die aktuelle Typhierarchie anzeigt. Die Basistypen werden dabei in diesem Viewer aufgelistet, wenn ein Typ abgeleitete Typen besitzt, werden diese Typen in den FoldElems in derselben Zeile aufgelistet. Zustzlich wird hinter jedem Typ die Gre, und - sofern vorhanden - die Anzahl der Methoden und die Anzahl der Pointer angegeben. HeapInspViewers.ModuleReachableTypes ^ ~: ffnet einen Viewer der die Typen der Objekte auflistet, die von dem angegebenen Modul (letzte Selektion) erreichbar sind. Die Informationen sind so wie die Informationen bei HeapInspViewers.ObjectsByType aufbereitet. Man kann die Liste dieser Typen nach Name (aufsteigend), nach der Anzahl der Objekte und nach ihrer Gre (absteigend) sortieren, indem man den jeweiligen Menpunkt anwhlt. HeapInspViewers.Finalizers: ffnet einen Viewer, der die Objekte, die sich in der Liste der zu finalisierenden Objekte befinden, auflistet. In dieser Liste werden der Objekttyp, die Adresse der Objekte, die Finalisierungs-Prozedur und das Mark-bit aufgelistet. HeapInspViewers.FreeBlocks: ffnet einen Viewer, der die momentanen freien Blcke, sortiert nach ihrer Gre und Position auf dem Heap (gleich ihrer Ordnung in der Freispeicherliste), auflistet. Bemerkung: Wenn dieses Kommando aufgerufen wird, werden einige Blcke allokiert, weshalb die Anzahl der freien Blcke reduziert ist. HeapInspViewers.ModuleLessObjects: ffnet einen Viewer, der diejenigen Objekte anzeigt, die kein (geladenes) Modul besitzen, d.h. der Typdeskriptor dieser Objekte hat einen Moduldeskriptor, der nicht mehr existiert. HeapInspViewers.Tasks: ffnet einen Viewer, der die momentan installierten Tasks auflistet. Bemerkung: Die obigen Kommandos sind in einem seperaten Modul, das erst zur Laufzeit geladen wird, weshalb beim ersten Aufruf eines solchen Kommandos ein zustzliches Modul geladen wird. Dies bewirkt allerdings, da die Liste der Test-entladenen Module zurckgesetzt wird. 1.5. Map HeapInspector.ZoomOut ~: Zeigt einen Gesamtberblick ber den Heap (in der Bitmap), die nur durch die maximale Hhe der Bitmap begrenzt ist. Jeder Block (32 Byte) wird dabei durch ein (oder mehrere) Pixel in der Bitmap reprsentiert. Es ist dabei mglich, da nur ein Teil des Heaps angezeigt werden kann. HeapInspector.ZoomOut xxx %: Vergrert den angezeigten Bereich des Heaps auf der Bitmap um den angegebenene Prozentsatz. Das Zoomen erfolgt symmetrisch zur Mitte der Bitmap, wenn der Anfang oder das Ende des Heaps erreicht ist, wird in diese Richtung nicht mehr weitergezoomt. (Das "%"-Zeichen ist nicht notwendig, aber es klrt die Bedeutung der Zahl vor dem Prozentzeichen). HeapInspector.Move Up ~, HeapInspector.Move Down ~: Bewegt die Bitmap um ein Viertel der Hhe auf- bzw. abwrts, bis das Ende bzw. der Anfang des Heaps erreicht ist. HeapInspector.Move Left ~, HeapInspector.Move Right ~: Bewegt die Bitmap um ein Sechstel der Breite nach links bzw. rechts, bis das Ende bzw. der Anfang des Heaps erreicht ist. Bemerkung: Diese Bewegung nach links oder nach rechts ist keine wirkliche Verschiebung nach links oder nach rechts, sondern eine Bewegung um einige Blcke nach oben oder unten, was einer Verschiebung nach links oder rechts hnlich sieht. HeapInspector.Move ^ ~: Allgemeines bewegen der Bitmap. Man mu dabei die Richtung (Up, Down, Left, Right) und die Anzahl der zu bewegenden Blocks (32 Bytes) oder Zeilen angeben. (Siehe auch Tastaturhandhabung). HeapInspector.SetMapTo Bottom ~, HeapInspector.SetMapTo Top ~: Bewegt die Bitmap zum Beginn bzw. zum Ende des Heaps. Der momentane Zoomfaktor (Gre des momentanen Heapabschnittes) wird dabei nicht verndert. HeapInspector.SetMapTo Center ~: Bewegt die Mitte der Bitmap in die Mitte des Heaps. Der Zoomfaktor wird nicht verndert. HeapInspector.SetMapTo ^ ~: .Setzt die Mitte der Bitmap auf die angegebene Adresse. Wenn dies nicht mglich ist (oberes oder unteres Ende des Heaps erreicht), wird die Bitmap mglichst nahe an diese Adresse gesetzt. (Der Zoomfaktor wird dabei nicht verndert). Bemerkung: Es knnen sowohl relative als auch absolute Adressen verwendet werden, um die Bitmap zu positionieren. (Wenn sich dabei die Adressbereiche berlappen, wird die relative Adresse genommen). HeapInspector.StartMapAt ^ ~: Setzt den Beginn der Bitmap auf die angegebene Adresse. Wenn notwendig, wird der Zoomfaktor der Bitmap verndert. Bemerkung: Es knnen sowohl relative als auch absolute Adressen verwendet werden, um die Bitmap zu positionieren. (Wenn sich dabei die Adressbereiche berlappen, wird die relative Adresse genommen). HeapInspector.ResizeMap Double: Verdoppelt die maximale Hhe der Bitmap (Begrenzt durch die Bildschirmhhe). HeapInspector.ResizeMap Half: Halbiert die maximale Hhe der Bitmap (Begrenzt durch eine Hhe von 16 Pixel). 1.6. Show HeapInspector.Show Map ~: Schaltet die Standard-Bitmap, die den Heap reprsentiert, ein und aus. Dieses Kommando invertiert den jeweiligen Status. HeapInspector.Show Collectable ~: Schaltet die Bitmap, die die "einsammelbaren" (d.h. lschbaren) Objekte auf dem Heap, die beim nchsten Durchlauf des Garbage Collectors gelscht werden, ein und aus (Invertierend). HeapInspector.Show NotCollectable ~: Schaltet die Bitmap, die die "nicht einsammelbaren" (d.h. nicht lschbaren) Objekte auf dem Heap, die beim nchsten Durchlauf des Garbage Collectors nicht gelscht werden, ein und aus (Invertierend). Die Bitmaps "Collectable" und "NotCollectable" ergnzen sich zu der Bitmap "All"). HeapInspector.Show Reachable ~: Schaltet die Bitmap, die die (transitiv) von dem selektierten Objekt erreichbaren Objekte anzeigt, ein und aus (Invertierend / Selektieren des Objekts mit der mittleren Maustaste => siehe Maushandhabung). HeapInspector.Show ReachedFrom ~: Schaltet die Bitmap, die die Objekte anzeigt, die (transitiv) das selektierte Objekt erreichen, ein und aus (Invertierend / Selektieren des Objekts mit der mittleren Maustaste => siehe Maushandhabung). Bemerkung: Wenn viele Objekte auf dem Heap sind (Verkettet mit vielen anderen Objekten, z.B.: Bume, lineare Listen, etc.), braucht dieses Kommando sehr lange. HeapInspector.Show ReachedFromModules ~: Listet die Module auf, die das momentan selektierte Objekt (Selektiert mit der mittleren Maustaste => siehe Maushandhabung) mit einer modulglobalen Variable erreichen. Wenn die Modi "Reachable" oder "ReachedFrom" aktiv sind, werden die entsprechenden Moduldescriptoren in der Bitmap angezeigt. HeapInspector.Show ReachedFromVariables ~: Listet die modulglobalen Variablen auf, die das momentan selektierte Objekt (Selektiert mit der mittleren Maustaste => siehe Maushandhabung) mit einer modulglobalen Variable erreichen. Wenn die Modi "Reachable" oder "ReachedFrom" aktiv sind, werden die entsprechenden Moduldescriptoren in der Bitmap angezeigt. HeapInspector.Show Moduleless ~: Listet diejenigen Objekte auf, die keinen gltigen Moduldescriptor haben (nicht in Moduldescriptor-Liste). Diese Objekte haben einen Typdescriptor, deren Zeiger auf den Moduldescriptor nicht mehr gltig ist. HeapInspector.Show Freeze ~: Friert die Bitmaps "Reached" und "ReachedFrom" mit der momentanen Selektion ein (Invertierend). Wenn nun jemand mit der Maus auf ein Objekt klickt (mit der mittleren Maustaste (MM) oder mit der Kombination Mitte-links (MM-ML)), bleibt das selektierte Objekt gleich. Dies ist ntzlich, wenn jemand die erreichten oder erreichbaren Objekte eines selektierten Objekts durchgehen will. Bemerkung: Alle Bitmaps werden wie sonst upgedated, nur die Selektion bleibt die gleiche. HeapInspector.Select ^ ~: Selektiert ein oder mehrere Objekte auf dem Heap, durch Verfolgen einer globalen Zeigervariable, Suchen eines Strings in einem Objekt, Suchen ein (oder mehrerer) Typdescriptoren oder Moduldescriptoren durch ihre Namen. Die gefundenen Objekte werden markiert in der Bitmap fr selektierte Objekte. a) Verfolgen einer Zeigervariable: Durch die Spezifikation einer Zeigervariable, wird der Wert des Zeigers angezeigt (NIL oder absolute Adresse (relative Adresse)). Syntax: Trace = "Trace" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]}. b) Verfolgen einer Zeigervariable und zeigen aller Objekte, die nur von diesem Zeiger verankert werden, d.h. wenn dieser Zeiger auf NIL gesetzt wird, werden alle angezeigten Objekte beim nchsten Durchlauf des Garbage-Collectors gelscht. Syntax: OnlyAnchoredBy = "OnlyAnchoredBy" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]}. c) Suche nach Objekten, die den spezifizierten String and der spezifizierten Position (relativ zum Beginn des Objekts) beinhalten. Standardposition (falls keine Position angegeben) ist 0. Syntax: Object = "Object" '"'String'"' [PositionInRecord]. d) Suche nach einem Typdescriptor mit dem spezifizierten Modul- und/oder Typnamen. Syntax: Typedescriptor = "Typedescriptor" [Modulename]"."[Typename]. e) Suche nach einem Moduldescriptor mit dem spezifizierten Modulnamen. Syntax: Moduledescriptor = "Module" Modulename. (Siehe Beschreibung in (Pseudo-)EBNF). HeapInspector.Index ^ ~: Setzt den (nicht exportierten) Indexwert HeapInspector.index. Dieser Wert kann benutzt werden um Variablen zu verfolgen (Mit HeapInspector.Select Trace ...) mit der Variable als Index. Mit den Kommandos Next, Previous, Reset, Show, ... kann man den Index auf einen Wert setzen und die Bitmaps werden automatisch upgedated. Dies hilft beim Durchlauf durch die Elemente eines Arrays. Zum Beispiel: HeapInspector.Select Trace HeapInspector.types.elems[HeapInspector.index].type ~ ... Verfolgt ein internes Array mit einem Pointer zu allen Typdescriptoren. HeapInspector.Select Off ~: Schaltet die Bitmap fr die selektierten Objekte ab. HeapInspector.Select ShowCommands ~: Zeigt einen Hilfetext fr das Kommando HeapInspector.Select (In EBNF). HeapInspector.Remain On / Off ~: Setzt den Status des HeapInspectors so, dass nur mehr Objekte angezeigt werden, die schon beim Aufruf dieses Kommandos vorhanden waren. D.h. in allen Bitmaps werden die Objekte, die neu hinzugekommen sind, nicht angezeigt. Bemerkung: Wenn ein Bereich auf dem Heap freigegeben und gleich darauf wieder allokiert wurde (bevor die Bitmap aufgefrischt wurde), wird das neue Objekt nicht als solches erkannt. HeapInspector.Show MarkedOnly ~: Schaltet (Invertierend) zwischen der normalen Anzeige und der exklusiven Anzeige der markierten Objekte um (Auswahl der markierten Objekte mittels der Kommandos HeapMap or HeapMarkObjects). HeapInspector.Show ObjectSizes ~: Schaltet (Invertierend) die Liste der Gren der Objekte auf dem Heap ein und aus (Die Gren sind aufgeschlsselt zur Basis 2x). HeapInspector.Show ColorizeDefaultBlocks ~: Schaltet (Invertierend) die Farbe der sonstigen Blcke (wie Sysblocks, Arrays ohne Zeiger, Arrays mit Zeiger und Typedescriptoren) ein und aus. HeapInspector.Show DefaultBlocks ~: Schaltet die Anzeige der sonstigen Blcke ein und aus (Eine eventuelle Einfrbung bleibt bestehen). HeapInspector.Status: Listet die Statusinformationen in einem Viewer auf. 1.7. Modules HeapInspector.UpdateModules: Bewirkt ein Update der internen Moduldescriptorliste. Wenn ein neues Modul geladen oder ein geladenes entladen wurde, wird die Anzahl der momentan geladenen Module ausgegeben.. Bemerkung: Ein Update der geladenen Module geschieht vor jedem Update der Bitmaps. HeapInspector.TestUnloadModules ^ ~: Entldt die angegebenen Module virtuell und zeigt die, nur von diesen Modulen verankerten, Objekte an (Diese Objekte wrden bei einem tatschlichen Entladen der Module freigegeben werden). Wenn ein angegebenes Modul von anderen Modulen importiert wird, werden diese Module ebenfalls entladen. Alle Objekte, die so freigegeben wrden, werden in der Bitmap "Collectable" angezeigt (inklusive denen die soundso freigegeben wrden). Das Test-unloading wird bei jedem Update neu durchgefhrt (mit den vorher angegebenen Modulen). Wenn Objekte von einem test-entladenen Modul und einem anderen Modul benutzt werden, werden nicht angezeigt, da auch bei einem wirklichen Entladen des Moduls diese Objekte nicht freigegeben wrden. Bemerkung: Ein explizites Update der Bitmap kann durch die Kommandos HeapInspector.Update oder System.Collect erzwungen werden. Bemerkung: Ein wirkliches Entladen eines Moduls kann u.U. das Freigeben von anderen Objekten bewirken, dies resultiert aus einem mglichen Aufruf des Terminations-Handlers, der beim Test-entladen nicht aufgerufen wird. Bemerkung: Wenn jemand einige Module fr das Test-entladen markiert hat und die Moduldescriptor-liste ndert sich, werden diese Markierungen gelscht (=> Erneuter Aufruf des Kommandos HeapInspector.TestUnloadModules). HeapInspector.TestUnloadModules ~: Schaltet das Test-entladen von Modulen aus. 1.8. Store (Edit.Store): Speichert die aktuellen Bitmaps (inkl. Statistiken). Bemerkung: Beim Speichern der Bitmap, wird die Bitmap als passive Bitmap (PElems) gespeichert. Wenn eine solche Bitmap wieder geladen wird, bewirkt die Maus nicht mehr die blichen Effekte. 1.9. Help Fr die folgenen Kommandos mu die Dokumentations-Textdatei fr den HeapInspector (HeapInspector.Text) vorhanden sein. HeapInspector.Help Documentation ~: Laden der Dokumentations-Textdatei. HeapInspector.Help DocuOfCode ~: Kurzbeschreibung des Sourcecodes. HeapInspector.Help Using Mouse ~: Hilfe fr die Mausbenutzung. HeapInspector.Help Using Keyboard ~: Hilfe fr die Tastaturbenutzung. HeapInspector.Help Authors ~: Autoren des HeapInspectors. HeapInspector.Help Code ~: Anzeigen des Sourcecodes. HeapInspector.Help Menu ~: Hilfe fr die Menleiste. HeapInspector.Help Menu-xxx ~: Hilfe fr den speziellen Menpunkt "xxx". 2. Maus- und Tastaturhandhabung  2.1. Maushandhabung Mausaktionen auf der Bitmap: a) Mittlere Maustaste (MM): Wenn mit der mittleren Maustaste auf ein Objekt geklickt wird, wird ein Viewer geffnet, der Informationen ber dieses Objekt zur Verfgung stellt. Wenn die Bitmap fr erreichbare Objekte ("Reachable") eingeschaltet ist, werden alle Objekte, die das selektierte Objekt erreicht, in dieser Bitmap angezeigt. Wenn der Mode "ReachedFromObjects" eingestellt ist, wird der Mode auf "Reachable" gendert. b) Mittlere Maustaste und anschlieend rechte Maustaste (MM + MR) oder rechte Maustaste (MR): Selektiert einen Teil der Bitmap fr das Hineinzoomen. Die Selektion ist Zeilenweise, d.h. die Selektion beginnt bei der ersten selektierten Zeile und endet bei der momentan unter dem Mauszeiger befindlichen Zeile. c) Mittlere Maustaste und anschlieend linke Maustaste (MM + ML) oder linke Maustaste (ML): Wenn die Bitmap fr erreichbare Objekte ("Reachable") eingeschaltet ist, werden alle Objekte, die das selektierte Objekt erreichen, angezeigt. Wenn der Mode "Reachable" eingestellt ist, wird der Mode auf "ReachedFromObjects" gendert. d) Andere Mausaktionen: Gleich einer passiven Bitmap (PElems). Eine Mausaktion im HeapInspector-Viewer setzt den Focus auf diesen Viewer. Die anschlieenden Tastatureingaben beziehen sich nun auf diesen Viewer (Navigation durch den Heap per Tastatur mglich). Bemerkung: Wenn ein Objekt mit der Maus angeklickt wird, kann dieses Objekt nicht mehr vom Garbage-Collector eingesammelt (d.h. gelscht) werden. 2.2. Tastaturhandhabung Page up / Page down: Bewegt die Ansicht (Bitmap) auf den Heap eine Seite auf- bzw. abwrts (Bis an den Beginn oder an das Ende). Die Hhe der Bitmap verndert sich dabei nicht. Cursor up / Cursor down: Bewegt die Ansicht (Bitmap) auf den Heap ein Fnftel auf- bzw. abwrts (Bis an den Beginn oder an das Ende). Die Hhe der Bitmap verndert sich dabei nicht. Cursor left / right: Bewegt die Ansicht (Bitmap) auf den Heap nach links bzw. nach rechts (Bis an den Beginn oder an das Ende). Die Hhe der Bitmap verndert sich dabei nicht. (Siehe HeapInspector.Move im Men-button "Map"). Cursor Pos1 / Ende: Bewegt die Ansicht (Bitmap) auf den Heap an den Beginn oder an das Ende des Heaps. Die Hhe der Bitmap verndert sich dabei nicht.. Bemerkung: Bevor man die Tastatur benutzen kann mu zuerst der Focus auf den HeapInspector-Viewer gesetzt werden (mittels einer Mausaktion im HeapInspector-Viewer).Syntax12b.Scn.FntMarkElemsAllocLinkElemsAlloc* *n *x** * * ** **(*6*@*** *!*"*<Syntax16.Scn.Fnt**#*$ Z    Zr nx I; Syntax12i.Scn.Fnt{* 4 X *x'D Z  Zr *7*L  Mt P      >  O)* e"8 3q6v *@> X j JTu!$*6!*6 (* ? cV*b PM+$N   ]!b+}#J> S$o ") / t# )!$+ Z ( Zy  6 JLIa |@~j*q vp Z  Zw  HeapInspector.ModHeapInspector.Mod%RHeapInspector.Mod7HeapInspector.ModbHeapInspector.Mod3HeapInspector.Mod*HeapInspector.Mod5gHeapInspector.Mod6HeapInspector.ModHc ) ;4HeapInspector.Mod' mimHeapInspector.Mod= HeapInspViewers.Mod!HeapInspDescs.Mod"HeapInspTracer.Mod<p#Syntax10.Scn.FntEnglish DeutschEnglishEnglish Deutsch$Syntax16b.Scn.FntAutorp\  p#Syntax10.Scn.FntEnglish DeutschEnglishEnglish Deutsch$Syntax20b.Scn.FntAnhang Syntax20b.Scn.Fntp^p#Syntax10.Scn.FntEnglish DeutschEnglishEnglish Deutsch$Syntax14b.Scn.Fnt,,Anhang A: Beschreibung der Kommandos in EBNF+p Syntax10b.Scn.Fnt  0 Syntax10i.Scn.Fnt       "   !  &   , )     C    !  u п Dp#Syntax10.Scn.FntEnglish DeutschEnglishEnglish DeutschaSyntax14b.Scn.Fnt@Syntax12.Scn.FntSyntax12b.Scn.Fnt";;LinkElemsAlloc*3*{Syntax12i.Scn.Fnt*6CN Anhang B: Beispiele von mglichen Anwendungen des HeapInspectors Die folgenden Beispiele sollen Programmierern und anderen Benutzern helfen, die Funktionen des HeapInspectors zu verstehen. Das kann ntzlich sein, wenn jemand Probleme mit einem Programm im Oberon System hat, oder wenn jemand zu Lehr- oder Lernzwecken Informationen ber das Oberon System bentigt (wie z.B. ber den Garbage Collector, die Finalisierung von Objekten, die Abhngigkeiten von Modulen untereinander, die Typhierarchie, ...). Beispiel 1: Zu wenig Speicher frei Problem: Wenn jemand ein Programm starten will, welches mehr Speicher bentigt, als aktuell verfgbar ist (Das Problem taucht vor allem auf, wenn jemand das Oberon System mit wenig Speicher startet), ist meist nicht bekannt, in welcher Reihenfolge momentan geladene Module entladen werden mssen, da das Kommando System.ShowModules nur alle Module anzeigt, jedoch nicht die Abhngigkeiten untereinander. Aus diesem Grund ist es fr jemanden, der die Modulhierarchie nicht so genau kennt, schwierig, diejenigen Module auszuwhlen, die zuerst entladen (System.Free) werden mssen. Lsung: Um die Modulhierarchie anzuzeigen, gengt es das Kommando HeapInspViewers.ModuleHierarchy aufzurufen um sich die Abhngigkeiten anzeigen zu lassen. Die Module an der Spitze der Hierarchie befinden sich dabei unten und sind rot gekennzeichnet. Diese Module sind die ersten Kandidaten fr das Enladen mit System.Free. Beispiel 2: Fehlersuche in einem Programms Problem: Wenn jemand ein Programm geschrieben hat, das nicht korrekt arbeitet, taucht das Problem auf, da die Objekte, die auf dem Heap allokiert wurden, fr den Programmierter nicht zugnglich sind, weshalb dies die Fehlersuche mitunter stark einschrnkt. Lsung: Der HeapInspector verfgt ber verschiedene Kommandos um objekte auf dem Heap anzuzeigen. Hier einige Beispiele: a) Das Kommando HeapInspector.HeapMap ffnet einen Viewer mit einer Bitmap, die den Heap reprsentiert. Wenn jemand noch zustzlich diejenigen Objekte namentlich angibt, die das Programm verwendet, werden diese eingefrbt. Dies ist brauchbar wenn Datenstrukturen wie z.B. Bume, Listen, usw. verwendet werden und jemand das Einfgen und Entfernen von Objekten beobachten will. Die momentane Anzahl der Objekte wird dabei unterhalb der Bitmap anzgezeigt. Bemerkung: Wenn jemand ein Objekt aus einer Datenstruktur entfernt, mu das Kommando System.Collect aufgerufen werden, um das Objekt auch aus dem Heap zu entfernen. b) Wenn man nun mit der Maus auf ein auf der Bitmap angezeigtes Objekt klickt, wird ein Viewer geffnet, der Informationen ber dieses Objekt anzeigt. Dies erlaubt eine berprfung des Inhalts, der Methoden, Basistypen, ... eines Objekts, wodurch man das korrekte Arbeiten des Programms berprfen kann. Bemerkung: Es kann sein, da die von einem Programm allokierten Objekte ber den Heap verteilt sind. Wenn man diese Objekte jedoch auf einem Speicherbereich beschrnkt haben will, kann man einerseits versuchen die Objekte gleich nach dem Starten des Oberon Systems zu allokieren (Kein Durchlauf des GC inzwischen), oder andererseits versuchen ein Kommando aufzurufen, das die Lcher auf dem Heap fllt (z.B. durch das Compilieren eines Programms). (Funktioniert in den meisten Fllen). Dies liegt daran, da das Kommando NEW allokiert die Objekte an der niedrigsten mglichen Adresse, weshalb die neu allokierten Objekte die Lcher im Speicher auffllen. Beispiel 3: Objekte auf dem Heap werden nicht freigegeben Problem: Der Garbage Collector gibt nur Objekte frei, die nicht von einem Pointer erreichbar sind: Wenn nun vergessen wird, einen Pointer auf NIL zu setzen, kann es sein, da ein oder mehrere nicht mehr bentigte Objekte (in Datenstrukturen wie z.B.: Bumen, doppelt verkettete Listen, ...) nicht freigegeben werden. Wenn eine solche Datenstruktur sehr gro ist, kann der belegte Speicherplatz dieser Objekte zu einem Problem werden. Lsung: Man kann alle Objekte eines bestimmten Typs in einer bestimmten Farbe einfrben. Durch das Anklicken eines solchen Objektes wird ein Viewer mit Informationen ber dieses Objekt geffnet. Wenn man nun wissen will, welche Module dieses Objekt verankern, zeigt ein Klicken auf "Show" und "HeapInspector.Show ReachedFromModules" alle Module an, die das Objekt verankern. Die einzelnen globalen Variablen die das selektierte Objekt verankern, werden durch ein Klicken auf "Show" und "HeapInspector.Show ReachedFromVariables" angezeigt. Beispiel 4: Suchen nach einem Objekt in Datenstrukturen (Fehlersuche) Problem: Das Problem ist hier hnlich dem in Beispiel 2, aber etwas komplexer. Wenn ein Programmierer ein Programm geschrieben hat, das ein oder mehrere Datenstrukturen verwendet, und dieser Programmierer die Objekte in den Datenstrukturen berprfen will, hat er das Problem, da er nicht wei, welche Datenstrukturen welche Objekte enthalten (z.B.: wenn ein Objekt von einer Datenstruktur ein eine andere transferiert wurde). Lsung: Man kann alle Objekte eines bestimmten Typs in einer bestimmten Farbe einfrben. Durch das Anklicken eines solchen Objektes wird ein Viewer mit Informationen ber dieses Objekt geffnet. Wenn man ein spezielles Objekt sucht (und es sind zu viele Objekte von diesem Typ vorhanden um dieses Objekt durch Anklicken aller Objekte zu finden), kann man dieses Objekt mit einem String markieren (mu im Quelltext des Programms geschehen) und es sich anschlieend mit dem Kommando "HeapInspector.Select Object 'This is the searched object' X" (where X specifies the position of the string in the record) auf einer Bitmap anzeigen lassen. Wenn man dann sehen will, in welcher Datenstruktur dieses Objekt verankert ist, bekommt man durch Klicken auf "Show" und "HeapInspector.Show ReachedFromVariables" den Modul- und den zugehrigen Variablennamen (=> Datenstruktur) angezeigt, die das Objekt verankern. 0e *' w*{ *6 ?h gHz @pDocumentation of Heap-Inspector  by Martin Rammerstorfer (MR) <== Please select language / Bitte Sprache whlen  Contents ()  1. The menubar 1.1. Close 1.2. HeapInspector 1.3. GC (Garbage Collector) 1.4. Info 1.5. Map 1.6. Show 1.7. Modules 1.8. Store 1.9. Help 2. Mouse and keyboard input 2.1. Mouse input 2.2. Keyboard input 3. Implementation 3.1 HeapInspector.Mod 3.1.1 Procedures for reset and set of data 3.1.2 Procedures for storing specified blocks on a set-array 3.1.3 Procedures for text operations 3.1.4 Procedures for module / type descriptor operations 3.1.5 Procedures for event-handling (selection) 3.1.6 Commands for setting the modes for Garbage-Collector 3.1.7 For miscellaneous use: MoveMap, DrawBlock, SetPtrReach, ReadMarkNames 3.1.8 Procedures for visualizing the objects on the heap on different criteria 3.1.9 Commands for update and marking objects 3.1.10 Commands for changing and showing the status of HeapInspector 3.2 HeapInspViewers.Mod 3.3 HeapInspDescs.Mod 3.4 HeapInspTracer.Mod 4. Author Appendix A: Description of commands in EBNF B: Examples for using the HeapInspector 1. The menubar 1.1. Close (HeapInspector.Close): Closes the HeapInspector viewer. If the viewer is the least recently opened HeapInspector viewer, automatic update of the bitmap after GC is turned off. After clicking on HeapInspector.Close the menubar offers two possibilities for quitting the HeapInspector: - Close viewer: Closes only the current viewer. - Unload modules of HeapInspector: Closes the viewer and unloads all modules needed from the HeapInspector (i.e. HeapInspViewers (if loaded), HeapInspector, HeapInspDescs and Inspector). 1.2. HeapInspector HeapInspector.Update: Updates the bitmap and shows the actually existing objects on the heap. HeapInspector.HeapMap ~: Opens a HeapInspector viewer with the bitmap representing the heap. Old HeapInspector viewers remain visible, but all operations from the menu-bar of the (old and new) HeapInspector viewers refer to the new viewer. The new viewer has the same settings as the old viewer, but without marked objects. The first (optional) parameter of this command sets the maximum height of the bitmap in pixels, if this parameter is not specified, the maximum height is set to 220 pixels. Further parameters denote the types whose objects shall be marked (see the description below). Note: If you open a new HeapInspector-viewer and you don't close the old viewer, the bitmaps in the old viewer are changed to passive bitmaps (PElems). HeapInspector.HeapMap ^: Opens a HeapInspector viewer as described above, parameters are taken from the last selection. The first parameter is optional. If it is "NoSplash", no splash-window will be displayed when the bitmap is first drawn. The second parameter is also optional. It specifies the maximum height of the bitmap in pixels. The actual height of the bitmap is always lower than the maximum height, as each block must always be 1, 2, 4 or 8 pixels square. Therefore the bitmap may not need the full height. The default value is 220. Further parameters denote the types whose objects shall be marked (see the description below). The type must be qualified with the module in which it is declared. If one specifies a module name only, this is taken as a shortcut for all types declared in this module. If a star follows the type specification (e.g. Files*, Texts.ElemDesc*), this is taken as a shortcut for all types derived from the specified types including themselves (i.e. Files.Handle, Files.Buffer, ..., Texts.ElemDesc, PopupElems.ElemDesc, ...). Each typee specification introduces a new colour that will be used to mark the objects of those types (See also Appendix A). Note: The maximum number of typespecifications is 5. HeapInspector.HeapMarkObjects ^: Marks some specified objects like before, but there will not be opened a new viewer. 1.3. GC (Garbage Collector) HeapInspector.GCOnOff on: Turns on garbage collection. HeapInspector.GCOnOff off: Turns on garbage collection. HeapInspector.UpdateAfterGC on: Turns on automatic updates of the bitmap, i.e. the HeapInspector updates all bitmaps and statistics after garbage collection. HeapInspector.UpdateAfterGC off: Turns off automatic updates of the bitmap, after a following run of the Garbage-Collector, the viewer will not be updated (Explicit update with HeapInspector.Update is not disabled). System.Collect: Initiates garbage collection if garbage collection is turned on. 1.4. Info The following viewers are a snapshot from the actual heap, i.e. during an update of the bitmaps, the viewers will not be updated. HeapInspViewers.Modules: Opens a viewer displaying the currently loaded modules and the memory used by these modules. One can sort the list of modules by name (ascending), by the number of objects and by their size (descending) by clicking on the sort menubuttons. code: size of program code. data: size of data. refs: size of reference information. types: number of record types. total memory used: sum of code, data, refs, module descriptor size, ... is imported (dir / indir): number of modules which directly or indirectly import the respective module. imports (dir / indir): number of modules which the respective module imports directly or indirectly. If a module is specified for test-unloading (see section 1.7), there are two pluses ("++") after the number of imports. If another module imports a module that has been specified for test-unloading, it will also be test-unloaded and is marked with a plus ("+"). If one specify one (and only one) module at the top of the module hierarchy, all modules, which are needed only by the specified module (It works like the command "System.Free ModuleName* ~"), will be marked by a star after the number of imports, but these modules will not be test-unloaded. If a module is indirectly imported by a test-unloaded module, there is a hash ("#") after the number of "imports". Note: The number of direct imports is sometimes different from the number of modules in the import list in the source code, due to how the compiler resolves imports. Note: If modules are marked for test-unloading and a module is loaded or unloaded, these marks will be deleted. HeapInspViewers.ObjectsByModule: Opens a viewer displaying the currently loaded modules with the number of objects with types defined in the respective modules and the memory consumed by these objects. One can sort the list of modules by name (ascending), by the number of objects and by their memory consumption (descending) by clicking on the sort menu buttons. HeapInspViewers.ObjectsByType: Opens a viewer displaying the types declared in the currently loaded modules. For each record type the number of objects, the number of bytes consumed and the number of bytes including internal fragmentation are listed (internal fragmentation results from the fract that memory blocks are allocated in multiples of 32 bytes). One can sort the list of types by name (ascending), by the number of objects and by their memory consumption (descending) by clicking on the sort menu buttons. The parameters "Named" and "Classes" will show only the types which have a type name or the types which are classes (types with methods). Note: The types which have no type name, are types defined local to a procedure. HeapInspViewers.Imports: Opens a viewer displaying the currently loaded modules with the list of imported modules and a list for modules that import the respective module. Note: The number of direct imports is sometimes different from the number of modules in the import list in the source code, due to how the compiler resolves imports. HeapInspViewers.ModuleHierarchy: Opens a viewer displaying the module hierarchy. Modules which do not import other modules are at the base of the hierarchy (level 0). The level of other modules in one plus the maximum level of the modules imported by the respective module: n level (Module (i)) := 1 + Maximum (level (ImportedModule (j))) j := 1 Modules which are not imported by other modules are written in red, test-unloaded modules are written in blue and the modules which are imported indirectly by test-unloaded modules are written in green (blue has a higher priority than red). FoldElems after module names contain the list of modules imported by the respective module. HeapInspViewers.TypeHierarchy: Opens a viewer displaying the type hierarchy. Actual loaded types which are base types are shown in the viewer, if there are types derived from another type, these types are placed in the FoldElems in the same line as the corresponding base type. At the right of the typename the size of the type is shown, and if the type has methods or pointers, the number of methods and pointers is shown. The parameters "Named" and "Classes" will show only the types which have a type name or the types which are classes (types with methods). HeapInspViewers.ModuleReachableTypes ^ ~: Opens a viewer displaying the types of the objects which are reached from the specified module. The information displayed is like the information displayed with HeapInspViewers.ObjectsByType. One can sort the list of modules by name (ascending), by the number of objects and by their memory consumption (descending) by clicking on the sort menu buttons. HeapInspViewers.Finalizers: Opens a viewer displaying the objects which are in the list of the finalizing objects. In this list there will be shown the object type, the address of the object, the procedure for finalizing and the mark-bit. HeapInspViewers.FreeBlocks: Opens a viewer displaying the current free blocks ordered by their size and position on the heap (like their order in the free memory list). Note: If you call this command, some blocks will be allocated and so the free blocks will be reduced. HeapInspViewers.ModuleLessObjects: Opens a viewer displaying the objects which have no (loaded) module, i.e. the typedescriptor of the object has a moduledescriptor, which doesn't exist any more. HeapInspViewers.Tasks: Opens a viewer displaying the current installed tasks. Note: The commands above are in a separated module, and so if you call such a command at first time after starting HeapInspector, a new module is loaded into memory, and so the marks of the modules which are test-unloaded will be cleared. 1.5. Map HeapInspector.ZoomOut ~: Zooms out to the maximum height of the bitmap. Each memory block (32 bytes) is represented by one (or more) pixel(s) in the bitmap. It is possible that only a part of the heap can be represented in the bitmap of the specified height. HeapInspector.ZoomOut xxx %: Zooms out by the specified percentage. Zooming is symmetric with respect to the middle of the bitmap. If the start or the end of the heap is reached, zooming in this direction stops. (The "%"-character is not necessary, but clearifies the meaning of the number.) HeapInspector.Move Up ~, HeapInspector.Move Down ~: Moves up or down about a quarter of the height of the bitmap until the start or the end of the heap is reached. HeapInspector.Move Left ~, HeapInspector.Move Right ~: Moves the bitmap about a sixth of the width to the left or to the right until the start or the end of heap reached. Note: This is not really a move to the left or right. The start or the end of the bitmap within the heap is moved some blocks up- or downward, which looks like a shift to the left or to the right. HeapInspector.Move ^ ~: General moving of the bitmap. One must specify a direction (Up, Down, Left, Right) and the number of blocks (32 bytes) or lines that should be moved in the specified direction, until the start or the end of heap is reached. (See also keyboard-actions). HeapInspector.SetMapTo Bottom ~, HeapInspector.SetMapTo Top ~: Moves the bitmap to the start or to the end of the heap, the current zooming (size of the current by bitmap shown part of the heap) will not be changed. HeapInspector.SetMapTo Center ~: Moves the center of the bitmap to the center of the heap. Zooming will not be changed. HeapInspector.SetMapTo ^ ~: ... the center of the bitmap to the specified address. If this is not possible the specified address is as near as possible to the center of the bitmap (Zooming will not be changed). Note: Relative addresses can be used to position the bitmap as wll as absolute addresses (there could be a conflict, if the addresses are overlapping. In this case, relative addresses are taken). HeapInspector.StartMapAt ^ ~: Sets the start of the bitmap to the specified address. If necessary, the zooming of the bitmap changes. Note: Relative addresses can be used to position the bitmap as wll as absolute addresses (there could be a conflict, if the addresses are overlapping. In this case, relative addresses are taken). HeapInspector.ResizeMap Double: Doubles the maximum height of the bitmap (limited by the display height). HeapInspector.ResizeMap Half: Decreases the size of the bitmap to the half (limited by a height of 16 pixels). 1.6. Show HeapInspector.Show Map ~: Disables or enables the default bitmap representing the heap. This command toggles the origin status of the bitmap. HeapInspector.Show Collectable ~: Disables or enables the bitmap (toggle mode) displaying the objects which will be collected (deleted) during next garbage collection. HeapInspector.Show NotCollectable ~: Disables or enables the bitmap (toggle mode) displaying the objects which will not be collected (deleted) during next garbage collection. (The bitmaps "Collectable" and "NotCollectable" complements each other to the bitmap "All"). HeapInspector.Show Reachable ~: Disables or enables the bitmap (toggle mode) displaying the objects which are (transitively) reachable from the selected object (selected by a middle mouse click => see mouse-actions). HeapInspector.Show ReachedFrom ~: Disables or enables the bitmap (toggle mode) displaying objects which (transitively) reach the selected object (selected by a middle mouse click => see mouse-actions). Note: If there are many objects on the heap (linked with many other objects, like trees, linear lists, etc.), this option is very slow. HeapInspector.Show ReachedFromModules ~: Shows the modules which anchor the selected object (selected by a middle mouse click) by the module global variables. If the modes "Reachable" or "ReachedFrom" are active, the module descriptors are displayed on these bitmap. HeapInspector.Show ReachedFromVariables ~: Shows the module global variables which anchor the selected object (selected by a middle mouse click). If the modes "Reachable" or "ReachedFrom" are active, the module descriptors are displayed on these bitmap. HeapInspector.Show Moduleless ~: Lists the objects whose modules have been unloaded. These objects have a type descriptor whose reference to the module descriptor may no longer be valid, i.e. the module may no longer be in the list of loaded modules. HeapInspector.Show Freeze ~: Freezes (toggle mode) the "Reached" and "ReachedFrom" bitmap with the current selection. If one clicks with the middle mouse-key (MM) or middle-left mouse-keys (MM-ML) on a object, this does not change the currently selected object which can be useful when browsing the information about reached or reaching objects. Note: All bitmaps will be updated if an update occurs, only the current selection remains the same. HeapInspector.Select ^ ~: Selects one or more objects on the heap by tracing a global pointer-variable, by searching a string in an object, or by searching one (or more) type descriptor(s) or a module descriptor by their names. The found objects are marked in the bitmap for selected objects. a) Tracing a pointer-variable: By specifying a pointer variable. The value of the pointer is shown (NIL or absolute address (relative address)). Syntax: Trace = "Trace" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]}. b) Tracing a pointer-value and show objects that are reachable only by the specified pointer, i.e., if this pointer set to NIL, the objects reached from this pointer would be collected (deleted) during next garbage collection. Syntax: OnlyAnchoredBy = "OnlyAnchoredBy" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]}. c) Search for an object containing a given string at a specified position in the object (relative to the beginning of the object). Default value of the string position is 0. Syntax: Object = "Object" '"'String'"' [PositionInRecord]. d) Search for a type descriptor with a specified module name and/or type name. Syntax: Typedescriptor = "Typedescriptor" [Modulename]"."[Typename]. e) Search for a moduledescriptor with a specified module name. Syntax: Moduledescriptor = "Module" Modulename. (See description in (Pseudo-)EBNF). HeapInspector.Index ^ ~: Sets the (not exported) index value HeapInspector.index this value can be used to trace (With HeapInspector.Select Trace ...) with the variable as index. With the commands Next, Previous, Reset, Show, ... one can set the index to a value and the bitmaps will automatically updated. Helps tracing some indexes of a variable with an array. For example: HeapInspector.Select Trace HeapInspector.types.elems[HeapInspector.index].type ~ ... Traces through an internal array with pointers to all typedescriptors. HeapInspector.Select Off ~: Disables the bitmap for selected objects. HeapInspector.Select ShowCommands ~: Prints a help-text for using of the command HeapInspector.Select (in EBNF). HeapInspector.Remain On / Off ~: Sets the mode for showing only the remaining objects on the heap. If this mode is turned on, the objects which are allocated after the command was called won't be shown (In all bitmaps). Note: If an area on the heap is freed and allocated before a new update of the bitmaps, the new allocated object will not be detected as a new object. HeapInspector.Show MarkedOnly ~: Shows (toggle mode) only marked objects (specified by commands HeapMap or HeapMarkObjects). HeapInspector.Show ObjectSizes ~: Shows (toggle mode) a list of the sizes of the objects on the heap (in sizes to the power of 2). HeapInspector.Show ColorizeDefaultBlocks ~: Colorizes (toggle mode) default blocks (like sysblocks, arrays without pointers, arrays with pointers and typedescriptors). HeapInspector.Show DefaultBlocks ~: Shows (toggle mode) the default blocks on the bitmap (colorized or not). HeapInspector.Status: Lists status informations of the HeapInspector in a viewer. 1.7. Modules HeapInspector.UpdateModules: Updates the internal module descriptor list. If a new module is loaded or a module is unloaded, the number of the loaded modules will be printed. Note: An update of the loaded modules is performed before each update of the bitmap. HeapInspector.TestUnloadModules ^ ~: Tries to unload the specified modules in order to show which objects would be freed if these modules were unloaded. If the specified modules are imported by other modules, the importing modules will also be test-unloaded. All objects that would be freed are marked in the bitmap of collectable objects. Test-unloading is performed as part of each update with the currently set list of modules. If objects are used by test-unloaded modules and by other modules these objects would not be freed if the first set of modules were really unloaded. Likewise these objects are not marked as collectable due to test-unloading. Note: Explicit update of the bitmap can be enforced by HeapInspector.Update or System.Collect. Note: The result of a real unload of a module could cause the deletion of another objects on the heap. This is because of a possible termination-handler of a module which is not called during test-unloading. Note: If one has marked some modules for test-unloading, and the list of loaded modules changes, the marks for test-unloading will be cleared (=> Call command HeapInspector.TestUnloadModules again). HeapInspector.TestUnloadModules ~: Turns off test-unloading of modules. 1.8. Store (Edit.Store): Stores the actual bitmap (incl. statistics). Note: If one store a bitmap, it is stored as a passive bitmap (PElems). If such a bitmap is again loaded, clicking on the bitmap does not have the usual effects. 1.9. Help For the following commands, the documentation-file of the HeapInspector (HeapInspector.Text) must be available. HeapInspector.Help Documentation ~: Load documentation text file. HeapInspector.Help DocuOfCode ~: A short description of the source code. HeapInspector.Help Using Mouse ~: Help for mouse input. HeapInspector.Help Using Keyboard ~: Help for keyboard input. HeapInspector.Help Authors ~: Authors of the HeapInspector. HeapInspector.Help Code ~: Show source code. HeapInspector.Help Menu ~: Help for the menu-bar. HeapInspector.Help Menu-xxx ~: Help for the menu-bar-PopupElem "xxx".  2. Mouse and keyboard input  2.1. Mouse input Mouse actions on the bitmap: a) Middle mouse key (MM): If one click on the bitmap with the middle mouse key a new viewer will display some information about the selected object. If the bitmap for reachable objects is shown, all objects which are reachable from the selected object, are marked. If the mode of this bitmap is "ReachedFromObjects", it changes to the mode "Reachable". b) Middle mouse and then right mouse key (MM + MR) or right mouse key (MR): Selects a part of the bitmap for zooming in. Selection is done row-wise, i.e. the selection starts at the first selected row and ends at the current selected row. c) Middle mouse and then left mouse key (MM + ML) or left mouse key (ML): If the bitmap for reachable objects is displayed, the mode of the HeapInspector changes to the mode "ReachedFromObjects", i.e. the objects, which reach (transitively) the selected object, are marked. Every mouse action passes the input focus to the HeapInspector viewer. Therefore keyboard input will also be processed to navigate within the bitmap. Note: If you click on an object, the object will be selected, and so the object can't be collected by the Garbage-Collector. 2.2. Keyboard input Page up / Page down: Moves the view to the heap one side up-/downward (until end or beginning of heap). The height of the bitmap does not change. Cursor up / Cursor down: Moves the view of the heap about a fifth of its height upward. The height of the bitmap does not change. Cursor left / right: Moves the view of the heap to the right or to the left. The height of the bitmap does not change. (See HeapInspector.Move in menu elem "Map"). Cursor Pos1 / End: Moves the view of the heap to the start or to the end of the bitmap. The height of the bitmap does not change. Note: Before one can use the keyboard, you must pass the focus to this viewer by a mouse-click into the HeapInspector. 3. Implementation 3.1 HeapInspector.Mod 3.1.1 Procedures for reset and set of data These procedures are used for initializing and resetting the used global data. 3.1.2 Procedures for storing specified blocks on a set-array These procedures are used for marking objects on the heap in an array of set. PROC MapSet/MapSetMark; IF blockposition lays in array of set THEN set bits in the corresponding position of array of set END 3.1.3 Procedures for text operations These procedures are used for simplifying the handling of viewers, popups and text operations. 3.1.4 Procedures for module / type descriptor operations For operations on the internal module descriptor and type descriptor list. Operations are implemented in module HeapInspDescs. 3.1.5 Procedures for event-handling (selection) Procedures for handling mouse- and keyboard-events and for the immediate reactions on such events (invert bitmap, select zoom, find selected object, ...). PROC 3.1.6 Commands for setting the modes for Garbage-Collector For enabling and disabling the Garbage-Collector and the automatic update after garbage collection. 3.1.7 For miscellaneous use: MoveMap, DrawBlock, SetPtrReach, ReadMarkNames 3.1.8 Procedures for visualizing the objects on the heap on different criteria These procedures are used to get information about the objects, which are marked in the bitmap. PROC VisualizeHeapMarked; FOR all objects on the heap DO IF markbit of object is set (GC) THEN Register object for drawing in VisualizeHeap; Count object (size, number, ...); PROC VisualizeHeap; Show Splashscreen on first call; FOR all objects on the heap DO Identify object type; Count objects (type, module, number, size, ...); Draw object in the corresponding color into the shown bitmaps; Remove Splashscreen if shown; Update pictures PROC MarkCollectable (); IF test-unload modules THEN remove selected modules from moduledescriptor-list; Mark reachable objects (works like garbage collector); VisualizeHeapMarked (); Remove all marks from objects on the heap; IF test-unload modules THEN insert selected modules into moduledescriptor-list; PROC VisHeapReachable; PROC CheckReach; Mark all objects reachable from specified pointer (using Kernel.Mark); Check if selected object was reached; Remove marks from all objects (if necessary); PROC CheckReachMod; FOR all global pointers in module DO Mark all objects reachable from this pointer (using Kernel.Mark); IF selected object was reached THEN set bit corresponding to this global pointer; Remove all mark-bits from objects on the heap; PROC Reach; Mark all objects reachable from specified pointer (reachPtr) (using Kernel.Mark); FOR all objects on the heap DO IF mark-bit is set, remove it, register and count (size, number, ...) PROC ModReachedFrom; FOR all loaded modules DO Check if module reaches selected objects; Print name of module (and name of global variable in module, if selected); PROC ReachedFrom; FOR all objects on the heap DO Show progress; Check if ESC-Key pressed; IF object has pointers THEN Trace all pointers of object; IF selected object is reached THEN register object; Remove all marks from marked objects. IF an object is selected THEN call specified procedures; PROC VisHeapSelected; PROC SelectTypedesc; IF module specified THEN search only for typedescriptors declared in this module; ELSE search through all typedescriptors; FOR all typedescriptor selected above DO IF typedescriptor-name fits to search-pattern THEN Register typedescriptor-object; Count typedescriptors (size, ...); PROC SelectModuleDesc; Search for module with specified search-pattern; IF module found THEN Register moduledescriptor-object; Count moduledescriptor (size, ...); PROC SelectTrace; Read first name of search-pattern; IF number THEN RETURN number; ELSIF only module specified THEN SelectModuleDesc ELSE Find module; Search in global variables for name of variable; FOR all specified names in trace-pattern DO IF variable-name THEN search variable and trace into (Record) ELSE (* index *) Call SelectTrace recursively (Trace global number-variable or get number); IF traces variable is a pointer THEN Register traced object; ELSE Error; PROC SelectOnlyAnchoredBy; Save and remove selected pointer; MarkCollectable; (* Mark all reachable objects *) Restore selected pointer; Trace reachable objects from selected pointer and register (marked objects minus not collectable objects); PROC SelectObjects; FOR all objects on the heap DO IF object has the specified string at the specified position THEN Register object; CASE kind of selecting objects call corresponding local procedure; PROC HeapDraw; IF main-viewer opened THEN Show bitmaps; Update or reset internal statistics; Prepare data for viewing reachable, selected and marked objects (if selected); VisualizeHeap (); IF main-viewer opened THEN Print textual statistics 3.1.9 Commands for update and marking objects For changing the marked objects, to open a new HeapInspector viewer, for updating the current bitmap, to unload some modules, for closing the HeapInspector viewer and exiting the HeapInspector. PROC HeapMap; Read names of objects to mark; Open new main-viewer; HeapDraw; (* Draws heapmaps and statistics *) PROC HeapUpdate; IF main-viewer is open THEN delete text in viewer; HeapDraw; (* Draws heapmaps and statistics *) PROC HeapMarkObjects; Read names of objects to mark; IF main-viewer is open THEN delete text in viewer; HeapDraw; (* Draws heapmaps and statistics *) PROC TestUnloadModules; Read names of modules for test unloading; Update imports (check conflicts in imports); HeapUpdate; 3.1.10 Commands for changing and showing the status of HeapInspector These commands are used in the menu-bar to set the bitmap sizes, to show the status of the HeapInspector, to show the help (Documentation), etc.. 3.2 HeapInspViewers.Mod 3.3 HeapInspDescs.Mod 3.4 HeapInspTracer.Mod 4. Author Martin Rammerstorfer Anger 36 4201 Gramastetten Appendix Appendix A: Description of commands in EBNF HeapInspector.Close = . HeapInspector.Update = . HeapInspector.HeapMap = ['"'NoSplash'"'] [Number] {TypeSpecification}. (* max. 5 times *) HeapInspector.HeapMarkObjects = [Number] {TypeSpecification}. (* max. 5 times *) TypeSpecification = Module["."Type]["*"]. HeapInspector.GCOnOff = "on" | "off". HeapInspector.UpdateAfterGC = "on" | "off". HeapInspViewers.Modules = . HeapInspViewers.ObjectsByModules = . HeapInspViewers.ObjectsByType = ["Named" | "Classes"]. HeapInspViewers.Imports = . HeapInspViewers.ModuleHierarchy = . HeapInspViewers.TypeHierarchy = ["Named" | "Classes"]. HeapInspViewers.ModuleReachableTypes = Module. HeapInspViewers.Finalizers = . HeapInspector.ZoomOut = [Number ["%"]]. HeapInspector.Move = ("Up" | "Down" | "Left" | "Right") Number. HeapInspector.SetMapTo = "Bottom" | "Top" | "Center" | Position. HeapInspector.StartMapAt = Position. HeapInspector.ResizeMap = "Double" | "Half". HeapInspector.Show = {"Map" | "Collectable" | "NotCollectable" | "Reachable" | "ReachedFrom" | "ReachedFromModules" | "ReachedFromVariables" | "Moduleless" | "FreezeMap" | "MarkedOnly" | "ObjectSizes" | "ColorizeDefaultBlocks" | "DefaultBlocks"}. HeapInspector.Select = "Off" | "Trace" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]} | "OnlyAnchoredBy" Module{"."VarName ["["(Number | GlobalNumberVariable)"]"]} | "Object" '"'String'"' [PositionInRecord] | "Typedescriptor" [ModuleName]"."[TypeName] | "Moduledescriptor" ModuleName. HeapInspector.Index = IndexPosition | "Show" | "Next" | "Previous" | "Reset" | "Using". HeapInspector.Status = . HeapInspector.Remain = "On" | "Off". HeapInspector.UpdateModules = . HeapInspector.TestUnloadModules = {ModuleName} | ModuleName"*". HeapInspector.Status = . HeapInspector.Help = "Documentation" | "DocuOfCode" | "Authors" | "Code" | "Menu" | "Menu Close" | "Menu HeapInspector" | "Menu GC" | "Menu Info" | "Menu Map" | "Menu Show" | "Menu Modules" | "Menu Store" | "Menu Help" | "Menu Commands". Appendix B: Examples for using the HeapInspector The following examples should help programmers and other users to understand the using of the HeapInspector. This could help if you have some problems with a program in the oberon system, or if you would learn something about the oberon system (like the garbage collector, the finalizing of objects, the dependencies of modules, the type hierarchy, ...). Example 1: Too little memory Problem: If one want to run a program which needs more memory than actually available (this problem occurs often, if one starts the oberon system with little memory), one could not know which modules should be unloaded at first, because the command System.ShowModules only shows all modules and so someone who doesn't know very much about the module hierarchy in the oberon system, could not decide which modules are to unload (System.Free) at first. Solution: If one call the command HeapInspViewers.ModuleHierarchy, the modules which are on the top on the module hierarchy are printed in red. These modules are the best candidates for the unloading with System.Free. Example 2: Debugging a program Problem: If one has a program which doesn't work correct, the problem occurs, that the objects allocated on the heap are not easy to visualize and so someone has no possibilities to check the program. Solution: The HeapInspector provides various commands to visualize objects on the heap, here are some examples: a) The command HeapInspector.HeapMap opens a viewer with a bitmap representing the heap and if one specifies the type name(s) or module name(s) of the objects which use the program, the objects with the specified type or module are shown colorized. This is useful if there are queues, trees, or other data structures and one would trace the inserting and removing of objects. The number of counted objects of each selection is shown under the bitmap. Note: If one remove an object from the data structure, call the command System.Collect because the object remains on the heap until the next garbage collection. b) If one click (with the mouse) on an object shown on the bitmap, a viewer is opened with information about this object. This allows someone to check the contents, methods, base types, ... of an object and so someone could check if his program works correct. Note: It could be that the allocated objects are placed somewhere on the heap. If one want to place them on one part on the heap, you could start the program immediately afterr starting the oberon system (no GC-run between), or one call a program which fills the holes on the heap by allocating objects (e.g. compile a program). (Works in the most cases). This is because the command NEW allocates the objects with the lowest possible address and so, new allocated objects will be placed into such holes on the heap. Example 3: Some objects on the heap will not be freed Problem: The garbage collector frees only objects which are not reachable from any pointer, and so, if someone has forgotten to set a pointer to NIL, it could be that one or more objects (in an data structure like a tree, a double chained list, ...) were not deleted. If such a data structure is very large, the memory consumption of these objects could be a problem. Solution: One can mark all objects of a specific type in a colour, and so someone has coloured all interesting objects. By clicking on such an object a viewer opens with information about this object. If one want to see which modules anchores the selected object, the clicking on "Show" and "HeapInspector.Show ReachedFromModules" will show all modules which anchores this object. If one want to see the global variables in these modules which anchores the selected object, clicking on "Show" and "HeapInspector.Show ReachedFromVariables" will show the modules and the corresponding variables which anchores this object. Example 4: Searching for objects in data structures (Debugging) Problem: Problem is similar to Example 2, but more complex. If a programmer has written a program which uses one or more data structures, and this programmer wants to check the objects in these data structures, the programmer has the problem, that he doesn't know which data structure contains which object e.g., an object is removed from one and inserted into another data structure. Solution: One can mark all objects of a specific type in a colour, and so someone has coloured all interesting objects. By clicking on such an object a viewer opens with information about this object. If one want to search a specific object (and if there are too many objects to find the specific object by clicking on all marked objects), one could mark this object by a string (must be done in the source code of the program) and so the command "HeapInspector.Select Object 'This is the searched object' X" (where X specifies the position of the string in the record), shows the object in a Bitmap. If one want to see which data structure contains the specific object, clicking on "Show" and "HeapInspector.Show ReachedFromVariables" will show the module(s) and the corresponding variables (=>data structure) which anchores this object.