wguiheap.gml

开放源码的编译器open watcom 1.6.0版的源代码

.chap Heap Walker
.*
.if &e'&dohelp eq 0 .do begin
.section Introduction
.do end
.*
.np
.ix 'Heap Walker' 'introduction to'
The &company Heap Walker is a testing and debugging tool for Windows.
It allows you to do two things:
.begbull $compact
.bull
observe how memory is being used
.bull
view the contents of memory
.endbull
.begnote
.mnote Note:
Under Windows NT, the Heap Walker monitors only the memory used by
16-bit Windows applications.
.endnote
.np
.ix 'Windows NT' 'with Heap Walker'
.ix 'Heap Walker' ' and Windows NT'
Heap Walker enables you to locate corrupted data and allows you to
manipulate stored memory for testing purposes. In addition to these
functions, this tool allows you to optimize your memory usage.
.np
Heap Walker displays the stored memory, or objects, in the Heap Walker
window. Objects are blocks of memory that go together to make up the
global heap. The objects may contain information such as program
instructions, data, or program resources. You control Heap Walker
using the items from the menu bar.
.*
.section Using Heap Walker
.*
.np
This section discusses the following topics:
.begbull $compact
.bull
Starting Heap Walker
.bull
Quitting Heap Walker
.bull
The Heap Walker Menu Bar
.endbull
.*
.beglevel
.*
.section Starting Heap Walker
.*
.np
.ix 'Heap Walker' 'start'
.ix 'start' 'Heap Walker'
To start Heap Walker, double click on the Heap Walker icon. This opens
the Heap Walker window. The information list displayed is the last
list that was viewed during the previous Heap Walker session.
.keep 15
.figure *depth=2.28 *scale=63 *file='HW1' The Heap Walker window displays lists of memory objects
.*
.section Quitting Heap Walker
.*
.np
.ix 'Heap Walker' 'quitting'
.ix 'close' 'Heap Walker'
To close the Heap Walker session, choose Exit from the File menu of
the Heap Walker window.
.*
.section The Heap Walker Menu Bar
.*
.np
.ix 'Heap Walker' 'menu bar'
.ix 'menus' 'Heap Walker'
The menu bar consists of the following eight menus:
.begpoint
.point File
Save to a file and configure the session
.point Display
Select the type of information you want to appear on the Heap Walker
window
.point Sort
Select how you want to sort the information in the Heap Walker window
.point Object
Work with the items in the Heap Walker window by viewing, removing,
and reordering them
.point Local
Work with Local Heaps
.point Global
Work with the Global Heap
.point Alloc
Allocate blocks of memory for testing purposes
.point Help
Access on-line help information
.endpoint
.*
.endlevel
.*
.section Configuring the Heap Walker Session
.*
.np
.ix 'Heap Walker' 'configure'
.ix 'configure' 'Heap Walker'
There are many aspects of Heap Walker that you can configure,
including setting the fonts, window positions, and save paths. Choose
the Configure item from the File menu. This opens the Heap Walker
Configuration dialog box where you customize the Heap Walker's
behavior.
.keep 17
.figure *depth='2.67' *scale=67 *file='HW2' On the Heap Walker Configuration dialog, you customize the Heap Walker's behavior
.np
The Configuration dialog is set up with defaults for all options.
To reset all options to their defaults, click the Defaults button.
.*
.beglevel
.*
.section Heap Walker: Configuring the File Name Paths
.*
.np
.ix 'file name paths' 'configuring in Heap Walker'
.ix 'paths' 'in Heap Walker'
.ix 'Heap Walker' 'configuring file name paths'
The Heap Walker window, the local heap window and the memory display
windows all have file menus with save items. When you choose the save
item one in these windows the currently displayed information is saved
to a filename generated by heapwalker.
.np
These file names are generated based on the entries in the File name
for... fields of the Configuration Dialog. The File name for Global
Saves affects filename generation for saves from the Heap Walker
window. The File name for Local Saves affects filename generation for
saves from the local walk window. The File name for Memory Dumps
affects filename generation for saves from the memory display window.
.np
The file names for saves are generated from the entered file name as
follows. If a path is specified for the filename then the generated
file will appear in the specified directory. The filename for the
generated file is formed by adding three digits to the end of the
specified file name to form a new filename that is unique in the given
directory.
.np
For example, if the File name for Memory Dumps field contains
"c:\mem\foo.txt" then all files saved from the memory display window
appear in the directory c:\mem and have filenames such as
"foo000.txt", "foo001.txt" and "foo003.txt".
.np
Beside each file name field in the configuration dialog is a Browse
button. Pressing this button opens a file selection dialog where you
can view your directory structure while picking the filename for that
field.
.*
.section Heap Walker: Configuring Window Behaviour
.*
.np
.ix 'window behaviour' 'configuring in Heap Walker'
.ix 'Heap Walker' 'configuring window behaviour'
As well as file name options, the Configuration dialog contains six
configuration options that you activate and de-activate using check
boxes. A description of each option follows.
.*
.beglevel
.*
.section Save Main Window Size/Position
.*
.np
Activating this option causes the size and position of the Heap Walker
window to be saved when you close the application. The next time you
open the Heap Walker application, the window appears with the same
size and same position as when you last closed it.
.*
.section Save Memory Window Size/Position
.*
.np
.ix 'memory window'
.ix 'Heap Walker' 'save memory window size'
Activating this option causes the size and position of the Memory
Display window to be saved when you close the application. The next
time you open the Memory Display window, it appears with the same size
and same position as when you last closed it.
.*
.section Allow Multiple Memory Display Windows
.*
.np
.ix 'memory display windows' 'multiple'
.ix 'Heap Walker' 'multiple memory display windows'
When this option is activated, you can open multiple Memory Display
windows. The new window may open on top of an existing window, but can
be moved and resized as necessary.
.np
When this option is not activated, selecting a second object to view
from the Heap Walker window closes the first Memory Display window and
opens the new Memory Display window in its place.
.*
.section Display Memory Info Window
.*
.np
.ix 'memory info window' 'in Heap Walker'
.ix 'Heap Walker' 'Memory Info window'
When this option is selected a Handle Information or Selector
Information dialog box appears whenever a Memory Display window is
opened. If this option is not activated the information box does not
appear, but it can be opened by choosing Show Info from the File menu
in the Memory Display window.
.*
.section Auto Position Memory Info Window
.*
.np
.ix 'Auto Position Info'
.ix 'Heap Walker' 'Auto Position Info'
The setting of the Auto Position Memory Info option in the
Configuration dialog determines the default setting of the Auto
Position Info feature in the Memory Display window.
.np
In the Memory Display window, activating the Auto Position Info
feature ensures that the information box is always attached to the
window. When deactivated, the Handle Information or Selector
Information dialog box moves separately from the Memory Display
window. You can turn on the auto position feature by selecting Auto
Position Info from the File menu on the Memory Display window.
.*
.section Display Resources
.*
.np
.ix 'display resources' 'in Heap Walker'
.ix 'Heap Walker' 'display resources in'
When the Display Resources option is activated, Heap Walker displays a
graphical image when you open the memory display window for an object
that represents a graphical resource.
.*
.endlevel
.*
.section Heap Walker: Saving the Current Configuration
.*
.np
.ix 'configuration' 'save in Heap Walker'
.ix 'Heap Walker' 'save configuration'
Normally, Heap Walker saves the configuration information, such as the
window size and position, only when the application closes. Choosing
the Save Current Configuration item from the File menu of the Heap
Walker window causes Heap Walker to save the current configuration
information. This saves the main window and Memory Display window
sizes and positions, even if the Save Main window size/position and
the Save Memory window size/position options in the Configuration
dialog box are not selected.
.*
.section Heap Walker: Setting the Font
.*
.np
.ix 'fonts' 'set in Heap Walker'
.ix 'Heap Walker' 'set fonts'
The Font item in the File menu allows you to set the font, style, and
size for the text in all Heap Walker windows. This item opens the Font
dialog box. Select the desired font details and click on OK to close
the dialog and apply the fonts.
.*
.endlevel
.*
.section Walking the Global Heap
.*
.np
There are four lists of information you can display in the Heap Walker
window. The Display menu allows you to choose a list to be displayed.
The lists Heap Walker can display are:
.begpoint $break
.point Entire Heap
.ix 'Entire Heap'
All of the memory objects on the global heap
.point Free Items
.ix 'Free Items'
All of the objects that are not currently allocated
.point LRU Items
.ix 'LRU Items'
The least recently used list items
.point Selector List
.ix 'Selector List'
All valid selectors
.endpoint
.*
.beglevel
.*
.section The Entire Heap
.*
.np
.ix 'Heap Walker' 'Entire Heap'
.ix 'Entire Heap'
Choosing Entire Heap from the Display menu displays a list of all the
global heap in the Heap Walker window. The global heap is a pool of
memory set aside by the system from which all program memory is
allocated.
.keep 15
.figure *depth='2.29' *scale=63 *file='HW3' Choosing the Entire Heap item displays the global heap.
.np
The following are the column headings that appear when the selected
display is Entire Heap, Free Items, or LRU Items.
.begpoint
.point Handle
An identifier assigned by the operating system to each object
on the global heap
.point Address
The physical address in memory of the first byte in the object
.point Size
The total number of bytes occupied by the object
.point Owner
The module that owns the memory
.point Flags
An indicator specifying the type of the object. The codes are F (fixed
memory) and D (discardable memory). A blank indicates that Heap Walker
is unable to determine if the object is fixed or discardable.
.point Lock
An identifier indicating if there is a lock on the object. L1
indicates there is a lock on the memory; P1 indicates there is a page
lock on the object; a blank indicates there is no lock on the object.
.point Heap
An indicator specifying if the object has a local heap. The code Y
indicates that the object has a local heap; a blank field indicates
there is no local heap.
.point Type
An indicator specifying the type of information in the object
.endpoint
.*
.section Free Items List
.*
.np
.ix 'Free Items'
.ix 'Heap Walker' 'Free Items'
The Free Items list contains all objects on the global heap that are
currently unallocated. Viewing the Free Items list allows you to see
how fragmented your free memory is. The Free Items list appears under
the same column headings as The Entire Heap list.
.*
.section LRU Items List
.*
.np
.ix 'LRU Items'
.ix 'Heap Walker' 'LRU Items'
The LRU Items list contains all items in the system that are currently
available to be discarded. The system discards memory when there is
not enough free memory to satisfy an allocation request from a
program. Memory is discarded based on a least recently used algorithm.
.np
Only the LRU list can be sorted by age. When sorted this way the
objects appear in order from newest to oldest. This means the first
object on the list will be the last item to be discarded. This allows
you to see the order in which the system will discard objects.
.np
To sort the LRU list, refer to the section
:hdref refid='srtlist'..
.np
The LRU Items list appears under the same column headings as The
Entire Heap list.
.*
.section The Selector List
.*
.np
.ix 'Selector List'
.ix 'Heap Walker' 'Selector List'
The selector list displays all valid ring three selectors in
the system. This list also shows descriptor table information
about each selector.
.keep 15
.figure *depth='2.29' *scale=63 *file='HW4' The Selector List displays all valid ring three selectors.
.np
.ix 'Heap Walker' 'Memory Display window'
.ix 'Memory Display window'
You can view the data accessible by a selector by double clicking on
its entry in the list. When you do this a Memory Display window
appears. Attached to this window is a Selector Information dialog
box that contains the information about the chosen selector that was
displayed in the selector list.
.np
The following are the column headings that appear when the
Selector List is displayed.
.begpoint
.point Sel
The selector that information on this line refers to
.point Base
The lowest linear address accessible using this selector
.point Limit
The number of bytes of memory that this selector allows you to access.
The greatest linear address accessible using this selector is
.us Base
plus the
.us Limit.
(i.e. <sel>:<limit>)
.point Gran
The granularity of the selector
.point Type
A value indicating if this selector provides execute access. This
value contains the value
.us code
if execute access is provided. Otherwise the field contains
.us data.
.point DPL
The privilege level for this selector. This determines the privilege
level that a task requires to access this memory.
.point Access
The operations that are allowed on memory using this selector. The
codes in this field are R (read), W (write), and Ex (execute).
.point Big
A code indicating if the selector's B flag (bit 54) is set. A
.us Y
in this column indicates the flag is set. A blank indicates the
flag is not set.
.endpoint
.*
.endlevel
.*
.section *refid=srtlist Sorting the Lists
.*
.np
.ix 'Sort menu' 'in Heap Walker'
.ix 'Heap Walker' 'Sort menu'
The items that appear in the Sort menu depend on the list
selected from the Display menu. The Sort items allows you to organize
the displayed information, making objects easier to find. There are two
ways to sort information in Heap Walker.
.begbull $compact
.bull
Choose the desired sort method from the Sort menu
.br
or
.br
.bull
Click once on the column heading by which you want to sort.
.endbull
.np
Only those headings appearing in the Sort menu change the
organization of the displayed information when selected.
.np
The following is a list of the headings by which you can sort the
displayed information. Some headings have a secondary sort feature.
For example, when you sort by Type, Heap Walker first sorts the
Type field alphabetically, then organizes objects of the same Type
by Owner. Where applicable, the secondary sort appears in parentheses.
.np
For the Entire Heap, Free Items, and LRU Items lists: