wprof.gml

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

.np
.ix 'Windows 3.x' 'sampler'
.ix 'sampler' 'Windows 3.x'
The Windows 3.x sampler (&smpwinup) will sample both 16-bit and 32-bit
Windows applications.
The sampler will only run under Windows 3.x 386 enhanced mode.
You must also include the "device" specification listed below in the [386Enh]
section of your SYSTEM.INI file.
.millust begin
DEVICE=C:&pathnamup.\BINW\WDEBUG.386
.millust end
When starting the sampler, you will be presented with a window to
select the executable and to specify the sampling rate.
.np
Once you start the sampler, a log window will appear.
This will report the state of the sampled program (it does not in any
way interfere with the program as it is running).
Once the program terminates, this window will remain.
The sample file will be placed in the same directory as the program
you are sampling, and will have the extension &smpextup..
.np
A well-behaved Windows application should have very few samples inside
the application.
Final development of a Windows application should involve a phase
where the application is analyzed so that it does not consume large
amounts of CPU time without yielding to Windows 3.x.
.np
To start the sampler, double-click on the &smpname icon.
Enter a command in the prompt dialogue box.
.millust begin
[wsample_options] program [arguments]
.millust end
.np
The following options are available under Windows.
.seesmpopt
.begnote
.note /r=<rate>
Rates from 1ms to 1000ms are allowed.
.note /b=<size>
Sizes from 1K to 64K are allowed.
.note /f=<file>
Specify the name of the sample file.
.endnote
.*
.section *refid=smpntr Using the Sampler with Win32
.*
.np
.ix 'Win32' 'sampler'
.ix 'sampler' 'Win32'
The Win32 sampler (&smpntup) will only sample Win32 applications
such as those that run under Windows 9x or Windows NT and later
operating systems.
It cannot be used to sample 16-bit applications.
When starting the sampler, you will be presented with a window to
select the executable and to specify the sampling rate.
.np
Once you start the sampler, a log window will appear.
This will report the state of the sampled program (it does not in any
way interfere with the program as it is running).
Once the program terminates, this window will remain.
The sample file will be placed in the same directory as the program
you are sampling, and will have the extension &smpextup..
.np
To start the sampler,
double-click on the &smpname icon.
Enter a command in the prompt dialogue box.
.millust begin
[wsample_options] program [arguments]
.millust end
.np
The following options are available under Win32.
.seesmpopt
.begnote
.note /r=<rate>
Rates from 1ms to 1000ms are allowed.
.note /b=<size>
Sizes from 1K to 64K are allowed.
.note /f=<file>
Specify the name of the sample file.
.endnote
.*
.*
.section *refid=smpnw Using the Sampler with NetWare 386
.*
.np
.ix 'NetWare 386' 'sampler'
.ix 'sampler' 'NetWare 386'
The sampler is also available for sampling the execution of NetWare
Loadable Modules.
The sampler (an NLM itself) will load and execute the program with
arguments.
.exam begin
load &smpnov [wsample_options] program [arguments]
.exam end
.cp 4
.np
The following options are available under NetWare:
.begnote
.note /r=<rate>
Rates from 1ms to 55ms are allowed.
.note /b=<size>
Sizes from 1K to 64K are allowed.
.note /f=<file>
Specify the name of the sample file.
.endnote
.*
.endlevel
.*
.chap *refid=prfrun The &prfname
.*
.if &e'&dohelp eq 0 .do begin
.*
.section *refid=prfover Profiler Overview
.*
.do end
.np
.ix 'profiler'
.ix '&prfname'
.ix '&prfcmdup'
The profiler reads the information from sample files and displays the
results as a graph.
Regions of concentrated activity are visible and may be explored by
zooming in to successive levels of detail.
.refalso smprun
.*
.beglevel
.*
.section *refid=prfzoom Zoom-In and Backout
.*
.np
.ix 'zoom' 'profiler'
.ix 'back out' 'profiler'
.ix 'profiler' 'zoom'
.ix 'profiler' 'back out'
The profiler allows you to
.us zoom-in
to successively more detailed views of your program.  You may also
.us back-out
of any detail view.
The levels of detail available are:
.begnote
.note Sample
This is a sample file.  The profiler can show you information from
several sample files at once.
.note Image
A sample file may consist of several images.  These are your main
executable file and any Dynamic Link Libraries (DLL) or NetWare
Loadable Modules (NLM) that your application called while
executing.
.note Modules
An image may consist of several modules.  Each module is a
compilation unit.  It consists of all the source code generated by
one invocation of the compiler.
.note Files
A module may be made up of several files.  Your application may
contain code that is generated by included files.
.note Functions
A file may contain several functions.  These are all of the global
functions that are defined within that file.
.note Source Lines
A function is made up of one or more source lines.
.note Assembler instructions
Each source line generates zero or more lines of assembler instructions.
It is possible to get
clues about expensive operations from the number of samples found
at each instruction.  For example, the C statement "i = j + k * l"
will generate a multiply instruction.  If you inspected the
assembler instructions, you might find that the multiply instruction took
the majority of the time in question.
.endnote
The process of moving from higher levels to lower levels, say, from
"modules" to "functions", is called
.us zooming in.
Moving from lower levels to higher levels ("assembler instructions" to "source
lines") is called
.us backing out.
As you zoom into your program the size of the region will get smaller
but the amount of detail will increase.
Likewise, backing out will restore previous levels to the larger
regions and reduced detail.
You may zoom-in and back-out of detail views in order to explore
your applications execution characteristics.
.*
.section *refid=prfsmp Samples
.*
.np
.ix 'samples' 'profiler'
.ix 'sampler data'
.ix 'profiler' 'samples'
After you have run the sampler, you are left with a sample file.
It contains a record of all locations where your program was
interrupted by the sampler.  A
.us sample
is a record of the instruction pointer within the program at the
point in time that the interrupt occurred.  Regions of the program
that consume large amounts of execution time have a larger number
of samples associated with them.
.*
.section *refid=prfperc Absolute and Relative Percentages
.*
.np
.ix 'absolute percentages' 'profiler'
.ix 'relative percentages' 'profiler'
.ix 'profiler' 'absolute percentages'
.ix 'profiler' 'relative percentages'
The most important piece of data that the profiler provides is the
percentage of time that a region of code contributes to total
execution time.
At the highest level (images), these percentages reflect each image's
contribution to the total execution time.
As you successively zoom into modules and functions, you may
become interested in the relative percentages.
.np
The percentage of time that a region contributes to the total
program execution time of the
.us program
is called an
.us absolute
percentage.
The percentage of time that a piece of a region contributes to the total
execution time
.us of your current detail level
is called a
.us relative
percentage.
.np
As you zoom in to the source and assembly views, the absolute
percentages of execution time may get quite small.  The relative
percentages help you to get a feel for the proportion of time
involved within the detail view, but don't get fooled into
thinking that a routine contributes more than it actually does.
Your decisions about which code to optimize should always be
based on absolute percentages.
.*
.endlevel
.*
.section *refid=prfui The &prfname. User Interface
.*
.figure *depth='3.4' *scale=51 *file='WPROF01' The Main Profiler Screen
.np
The profile screen is divided into six areas.  In the middle of
the screen is the
.us information area.
It contains relative and absolute percentage numbers.  The top half of
the screen is the title area.  The bottom half of the screen is the
detail view.  The menu is displayed at the top of the screen. The
bottom line displays status information.
.*
.beglevel
.*
.section *refid=prftitl The Title Area
.*
.figure *depth='1.7' *scale=55 *file='WPROF02' The Profiler Title Area
.np
As you zoom in and back out, the title area adds and removes lines
to show you that path that you took to your current detail view.
You can back out to any level displayed in the title area by
double clicking on that line.
.*
.section *refid=prfinfo The Information Area
.*
.figure *depth='1.9' *scale=53 *file='WPROF03' The Profiler Information Area
.np
The information area is updated as you move around in the detail
view.  The red and green percentage numbers give you numerical
values that correspond to the histogram bar on the current line in
the detail area.  The red number represents the line's percentage
of total execution time.  The green number represents the line's
percentage of the time spent within the current detail level.
.*
.section *refid=prfdetl The Detail View
.*
.figure *depth='3.4' *scale=51 *file='WPROF04' The Profiler Detail View
.np
The detail view shows you a list of one of the following:
.begbull $compact
.bull
Image Names
.bull
Module Names
.bull
File Names
.bull
Routine Names
.bull
Source Lines
.bull
Assembler Instructions
.endbull
.np
On the left half of the screen is a histogram which shows the
number of samples at each location.  On the right is a list of
names.  If there are more lines than will fit on the screen, you
can use the cursor keys and scroll bars to move through the list.  As
you cursor through the list of names, or click on a name with the
mouse, the information area is updated to show statistics about
the current line in the detail area.
.np
If you find a line that is heavily executed, and you wish to
examine the it in more detail, double click on it, or cursor to it
and press F3 or ENTER.  You may back out of a detail view
by pressing F4 or BACKSPACE.  As you zoom in and back out, the
title area is updated to show that path you took to your current
detail area.
.*
.figure *depth='3.4' *scale=51 *file='WPROF05' The Profiler Assembly Detail
.np
The histogram will be drawn in two &colour.s, red and green.  The
red portion represents the absolute percentages of execution time for
each line.
The green and red portions, taken together, show the percentage of
a line
.us relative
to the current detail view.
For example, if a detail line represented 10% of the total execution
time, then the red absolute bar would take 10% of the histogram area.
If the entire digital view represented 20% of the execution time, then the
single detail line would have a green and red bar which would take
50% of the histogram area (10% is half the total time of the entire
detail view).
.*
.section *refid=prfmenu The Profiler Menu Bar
.*
.np
The Profiler's menu bar lets you perform operations.  You can
activate the menu bar by using the mouse, or by holding the ALT
key and pressing the key that corresponds to the highlighted character
in the menu bar.  There are five menu bars.
.beglevel
.*
.section *refid=prfmfil The File Menu
.*
.np
The File menu contains the following items:
.begnote
.note Open...
Open a new sample file.  A new window will be opened, and the
data from the sample file will be displayed in it.
.note Close
Close the current sample file.  The current window will be closed.
.note Options
This allows you to set profiler options.  See the section entitled
:HDREF refid='prfdopt'. for details.
.note System
Start a new operating system shell.  This option is only available
in the DOS version of the profiler.
.note Exit
Close your profiler session and exit.
.endnote
.*
.section *refid=prfmcnv The Convert Menu
.*
.np
The Convert menu allows you to select an output format to save
some of the raw information to a file.
The DIF format is supported by most of the major data manipulation or
spreadsheet programs.
The comma delimited format is a simpler format that is supported by
older software, and is easily manipulated by custom made software.
The Convert menu contains the following items:
.begnote
.note Current Module
Use this menu item to save out the information related to the current
module.
.note Current Image
Use this menu item to save out the information related to the current
image.
.note All Images
Use this menu item to save out the information related to the all of the
sample images.
.endnote
.*
.section *refid=prfmwin The Windows Menu
.*
.np
The Windows menu contains one menu item for each sample file you have
open.
Use this menu to switch between sample files.
.*
.section *refid=prfmact The Actions Menu
.*
.np
When you select an item from the Actions menu, it acts on the current
detail view.
To configure one of the actions across all windows,
see :HDREF refid='prfdopt'..
The Actions menu is identical to the floating popup associated with
the current window.
.refalso prfpop
The Actions menu contains the following items:
.begnote