wprof.gml

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

.* Pictures follow this informal code for naming:
.*
.*      PR?<name>
.*      ^ ^
.*      | +-- M - menu, D - dialogue box
.*      |
.*      +---- 2 letter constant meaning PRofiler
.*
:set symbol='smpdosup'  value='WSAMPLE.EXE'
:set symbol='smpos2up'  value='WSAMPLE.EXE'
:set symbol='smpplsup'  value='WSAMPPLS.EXP'
:set symbol='smprsiup'  value='WSAMPRSI.EXE'
:set symbol='smpwinup'  value='WSAMPLEW.EXE'
:set symbol='smpntup'   value='WSAMPLE.EXE'
:set symbol='smpnovup'  value='WSAMPLE.NLM'
.*
:set symbol='smpdos'    value='wsample'
:set symbol='smpos2'    value='wsample'
:set symbol='smppls'    value='wsamppls'
:set symbol='smprsi'    value='wsamprsi'
:set symbol='smpwin'    value='wsamplew'
:set symbol='smpnt'     value='wsample'
:set symbol='smpnov'    value='wsample'
.*
:set symbol='smpext'    value='~.smp'
:set symbol='smpextup'  value='~.SMP'
:set symbol='lstext'    value='~.lst'
:set symbol='lstextup'  value='~.LST'
.*
:set symbol='sysperup'  value='~.'
.if '&machine' eq '80386' .do begin
:set symbol='ccomp'     value='wcc386'
:set symbol='fcomp'     value='wfc386'
.do end
.if '&machine' eq '8086' .do begin
:set symbol='ccomp'     value='wcc'
:set symbol='fcomp'     value='wfc'
.do end
.*
.chap Profile Analysis Tools
.*
.np
This section describes how to use the profile analysis tools to enhance the
performance of your program. There are two profile analysis tools:
.begbull
.bull
The &smpname (the sampler)
.bull
The &prfname (the profiler)
.endbull
.np
You must use both of these tools to discover where your code is spending
time as it executes.
.np
First, you must run the
.us Sampler
.dot
The sampler starts your application and, at a predetermined interval,
records the location where your program is executing.
This information is saved in a "sample file".
It is a statistical sampling of your program's execution.
It is not exact information, but it is accurate enough to be a very
useful tool to enhance your program's performance.
.refalso smprun
.np
Second, you run the
.us Profiler
.dot
It reads the sample file and displays the sample information
graphically. You can use the profiler to examine the sample data
and narrow in on the places where your program spends large
amounts of time.
.refalso prfrun
.np
Once you have discovered heavily executed portions of your
program, you might want to rewrite then using a faster algorithm
or fine tune your implementation of the current algorithms.
.begnote
.mnote Note
You must compile and link the program with debugging information.
Use at least the
.us; d1
option when compiling and the
.us; debug all
option when linking.
.endnote
.*
.chap *refid=smprun The &smpname
.*
.if &e'&dohelp eq 0 .do begin
.*
.section Running The &smpname.
.*
.do end
.np
To run the sampler from the Integrated Development Environment,
click on the toolbar item that looks like a stopwatch.
.np
.ix 'sampler' 'command line format'
.ix 'command line format' 'sampler'
The sampler's command line syntax is shown below.
.mbigbox
&smpcmdup. [options] program [arguments]
.embigbox
.begnote
.mnote &smpcmdup.
is one of several versions of the sampler.
See the section entitled :HDREF refid='smpos'. for a description of
how to run the sampler under various environments.
.mnote options
is a list of valid sampler options, each preceded by a slash
("/") or a dash ("&minus.").
Options may be specified in any order.
.mnote program
is the name of the program to be sampled.
.mnote arguments
is the set of arguments passed to the program.
The program behaves just as if it were executed directly from the
command line.  If you normally run your program using:
.millust begin
C>program [arguments]
.millust end
then it may be sampled using the following command:
.millust begin
C>&smpcmd program [arguments]
.millust end
.pc
By default, the output of &smpcmdup is a sample file with the same
name as the executable but with an extension of &smpextup..
In the above example, it would be called
.fi PROGRAM&smpextup..
.endnote
.*
.section *refid=smpopts Sampler Options Summary
.*
.np
.ix 'sampler command line' 'options'
.ix 'sampler command line' 'help'
.ix 'sampler command line' 'summary'
The sampler has several command line options.
A summary of the available options is displayed on the screen by
executing the "&smpcmdup" program appropriate for your system.
.code begin
C>&smpcmd

Usage: wsample [options] program [program arguments]
Options:
    /b=<size> specify the buffer size for samples (default: 63)
    /f=<file> specify the output filename for the sample file
    /r=<rate> specify the sampling rate

    <size>    is a number in the range 1 to 63 (default: 63 kb)
    <rate>    is a number (range 27 to 1000) specifying the approximate
              time interval (in milliseconds) between samples
              (default: 55)

   '#' may be used instead of '=' in options (e.g., /b#10)

.code end
.*
.section *refid=smpopt Sampler Command Line Options
.*
.np
Command line options allow you
to control how much the program's execution will be affected by the
presence of the sampler.  System specific options are described in
detail in subsequent sections. The options that apply to all versions
of the sampler are:
.begnote
.ix 'sampler options' 'r'
.note /r=<sample_rate>
Specifies the approximate time between execution samples (in
milliseconds). The sampler will set up the system so that the program
will be interrupted in intervals of the number of milliseconds
specified on the command line. A smaller number will result in a more
accurate sample file. A larger number result in a less accurate
sample. If your program runs for a very short time, you should use the
smallest interval possible. The default value is system dependent and
it will be displayed if you enter "&smpcmdup" with no arguments. The
following example will sample the program's execution 200 times per
second.
.exam begin
C>&smpcmd /r=5 program
.exam end
.pc
.ix 'sampler options' 'b'
.note /b=<buffer_size>
Specifies the size of the sampler's internal buffer (in kilobytes).
The execution of the program will produce many samples which must be
recorded in the sample file.
The sampler stores the samples in an internal buffer until the buffer
is filled and must be written to the disk.
You may reduce the buffer size if you want to leave more memory for
your application program.
You should not make the buffer size so small that the sampler would
have to write samples to disk more than once a second.
The default size for the sample buffer is 63K.
In the following example, a buffer size of 10K will be used:
.exam begin
C>&smpcmd /b=10 program
.exam end
.pc
.ix 'sampler options' 'f'
.note /f=<fname>
Specify the name of the sample file.
Samples will be written to the specified file.
By default, a file with the same name as the executable and an
extension of &smpextup. is created.
.endnote
.*
.section *refid=smpos Sampler Operating System Considerations
.*
.np
There is a different version of the sampler to match each operating
system.
Some systems do not allow the sample rate to be adjusted.
Each sampler will provide information about any unique aspects of its
operation when you type its program name on the command line.
.exam begin
C>&smpcmd
.exam end
.pc
Here are the &smpname executable names provided.
.begpoint $break $setptnt 20
:DTHD.Operating System:
:DDHD.Command:
.point DOS
&smpdosup
.point OS/2
&smpos2up
.point DOS/4GW or DOS/4G
&smprsiup
.point 386|DOS-Extender
&smpplsup
.point Windows 3.x
&smpwinup
.point Win32
&smpntup
.point NetWare 386
&smpnovup
.endpoint
.np
.ix 'no samples'
.ix 'Virtual DOS Machine'
.ix 'real DOS'
.ix 'timer interrupt'
The sampler for an operating system such as DOS will not operate
correctly in an environment that is not strictly DOS such as
a Windows or OS/2 DOS box.
The sampler obtains its information about what was executing when a
timer interrupt occurs from the stack.
Unlike "real" DOS, the segment/offset on the stack in a protected-mode
environment supporting Virtual DOS Machines does not correspond to the
program that was executing at the time of the timer interrupt.
As a result, you must run the sampler in the real operating system
environment for which it was designed.
The same is true for Windows applications in a Win-OS/2 session.
.*
.beglevel
.*
.dm seesmpopt begin
For a further description of options, see :ZHDREF refid='smpopt'..
.dm seesmpopt end
.*
.section *refid=smpuse Using the Sampler with DOS
.*
.np
.ix 'DOS' 'sampler'
.ix 'sampler' 'DOS'
The following options are available under DOS.
.seesmpopt
.exam begin
C>&smpdos [wsample_options] program [arguments]
.exam end
.begnote
.ix 'sampler options' 'i'
.note /r=<rate>
Rates from 1ms to 55ms are allowed.
.note /b=<size>
Sizes from 1K to 64K are allowed.
Since DOS places a limit on the amount of memory
available to all programs,
you may need to use the "b" option to reduce the memory
requirements of the sampler, leaving more memory for your program.
.note /f=<file>
Specify the name of the sample file.
.note /i=<interrupt>
specify an interrupt to monitor
.np
This option allows you to assign any samples that occur while a
service interrupt is executing to the instruction following the
requesting INT instruction.
This will reveal the amount of time code spends "waiting" for
interrupt services.
The interrupt number specified is in base 16 (hex) and can be in the
range 20 to ff except for the range 34 to 3d which is reserved for
80x87 emulation.
.exam begin
C>&smpcmd /i=25 /i=26 program
.exam end
.ix 'sampler options' 'd'
.note /d
disable monitoring of the DOS interrupt
.np
By default, the DOS version of the sampler assigns any samples that
occur while a DOS interrupt is executing to the instruction following
the requesting INT 21H instruction.
This will reveal the amount of time code spends "waiting" for DOS to
complete a service.
This option can be used to disable this assignment of samples so that
the total time spent executing in DOS code may be determined.
.endnote
.*
.section *refid=smpos2r Using the Sampler with OS/2
.*
.np
.ix 'OS/2' 'sampler'
.ix 'sampler' 'OS/2'
The following options are available under OS/2.
.seesmpopt
.exam begin
C>&smpos2 [wsample_options] program [arguments]
.exam end
.begnote
.ix 'sampler options' 'i'
.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.
.note /s
start the application in a new session.  By default
the sampler starts your application in its own
session.  Use /s if you application is a PM application,
or requires its own session to run.
.endnote
.*
.section *refid=smp4gr Using the Sampler with DOS/4GW or DOS/4G
.*
.np
.ix 'DOS/4GW' 'sampler'
.ix 'sampler' 'DOS/4GW'
This version of the sampler uses one of DOS/4GW or DOS/4G to run the
sampler in 32-bit protected mode.
One of DOS4GW.EXE or DOS4G.EXE must be located in the path specified
in
.ev DOS4GPATH
or
.ev PATH.
The sampler will, in turn, invoke the program with any arguments
specified on the command line.
The following options are available.
.seesmpopt
.exam begin
:cmt. C>dos4gw &smprsi [wsample_options] program [arguments]
C>&smprsi [wsample_options] program [arguments]
.exam end
.begnote
.ix 'sampler options' 'i'
.note /b=<size>
Sizes from 1K to 64K are allowed.
.note /f=<file>
Specify the name of the sample file.
.endnote
.*
.section *refid=smpphar Using the Sampler with the Phar Lap 386|DOS-Extender
.*
.np
.ix '386|DOS-Extender' 'sampler'
.ix 'sampler' '386|DOS-Extender'
The sampler must be run using RUN386.
RUN386 will run the sampler in 32-bit protected mode which will invoke
the program with any arguments specified on the command line.
The following options are available.
.seesmpopt
.exam begin
C>run386 &smppls [wsample_options] program [arguments]
.exam end
.begnote
.ix 'sampler options' 'i'
.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
.*
.section *refid=smpwinr Using the Sampler with Windows 3.x
.*